util/src/TclTk/tk8.6.12/doc/menubutton.n

   1 '\"
   2 '\" Copyright (c) 1990-1994 The Regents of the University of California.
   3 '\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
   4 '\"
   5 '\" See the file "license.terms" for information on usage and redistribution
   6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   7 '\"
   8 .TH menubutton n 4.0 Tk "Tk Built-In Commands"
   9 .so man.macros
  10 .BS
  11 '\" Note:  do not modify the .SH NAME line immediately below!
  12 .SH NAME
  13 menubutton \- Create and manipulate 'menubutton' pop-up menu indicator widgets
  14 .SH SYNOPSIS
  15 \fBmenubutton\fR \fIpathName \fR?\fIoptions\fR?
  16 .SO
  17 \-activebackground      \-disabledforeground    \-padx
  18 \-activeforeground      \-font  \-pady
  19 \-anchor        \-foreground    \-relief
  20 \-background    \-highlightbackground   \-takefocus
  21 \-bitmap        \-highlightcolor        \-text
  22 \-borderwidth   \-highlightthickness    \-textvariable
  23 \-cursor        \-image \-underline
  24 \-compound      \-justify       \-wraplength
  25 .SE
  26 .SH "WIDGET-SPECIFIC OPTIONS"
  27 .OP \-direction direction Height
  28 Specifies where the menu is going to be popup up. \fBabove\fR tries to
  29 pop the menu above the menubutton. \fBbelow\fR tries to pop the menu
  30 below the menubutton. \fBleft\fR tries to pop the menu to the left of
  31 the menubutton. \fBright\fR tries to pop the menu to the right of the
  32 menu button. \fBflush\fR pops the menu directly over the menubutton.
  33 In the case of \fBabove\fR or \fBbelow\fR, the direction will be
  34 reversed if the menu would show offscreen.
  35 .OP \-height height Height
  36 Specifies a desired height for the menubutton.
  37 If an image or bitmap is being displayed in the menubutton then the value is in
  38 screen units (i.e. any of the forms acceptable to \fBTk_GetPixels\fR);
  39 for text it is in lines of text.
  40 If this option is not specified, the menubutton's desired height is computed
  41 from the size of the image or bitmap or text being displayed in it.
  42 .OP \-indicatoron indicatorOn IndicatorOn
  43 The value must be a proper boolean value.  If it is true then
  44 a small indicator rectangle will be displayed on the right side
  45 of the menubutton and the default menu bindings will treat this
  46 as an option menubutton.  If false then no indicator will be
  47 displayed.
  48 .OP \-menu menu MenuName
  49 Specifies the path name of the menu associated with this menubutton.
  50 The menu must be a child of the menubutton.
  51 .OP \-state state State
  52 Specifies one of three states for the menubutton:  \fBnormal\fR, \fBactive\fR,
  53 or \fBdisabled\fR.  In normal state the menubutton is displayed using the
  54 \fBforeground\fR and \fBbackground\fR options.  The active state is
  55 typically used when the pointer is over the menubutton.  In active state
  56 the menubutton is displayed using the \fB\-activeforeground\fR and
  57 \fB\-activebackground\fR options.  Disabled state means that the menubutton
  58 should be insensitive:  the default bindings will refuse to activate
  59 the widget and will ignore mouse button presses.
  60 In this state the \fB\-disabledforeground\fR and
  61 \fB\-background\fR options determine how the button is displayed.
  62 .OP \-width width Width
  63 Specifies a desired width for the menubutton.
  64 If an image or bitmap is being displayed in the menubutton then the value is in
  65 screen units (i.e. any of the forms acceptable to \fBTk_GetPixels\fR);
  66 for text it is in characters.
  67 If this option is not specified, the menubutton's desired width is computed
  68 from the size of the image or bitmap or text being displayed in it.
  69 .BE
  70 .SH INTRODUCTION
  71 .PP
  72 The \fBmenubutton\fR command creates a new window (given by the
  73 \fIpathName\fR argument) and makes it into a menubutton widget.
  74 Additional
  75 options, described above, may be specified on the command line
  76 or in the option database
  77 to configure aspects of the menubutton such as its colors, font,
  78 text, and initial relief.  The \fBmenubutton\fR command returns its
  79 \fIpathName\fR argument.  At the time this command is invoked,
  80 there must not exist a window named \fIpathName\fR, but
  81 \fIpathName\fR's parent must exist.
  82 .PP
  83 A menubutton is a widget that displays a textual string, bitmap, or image
  84 and is associated with a menu widget.
  85 If text is displayed, it must all be in a single font, but it
  86 can occupy multiple lines on the screen (if it contains newlines
  87 or if wrapping occurs because of the \fB\-wraplength\fR option) and
  88 one of the characters may optionally be underlined using the
  89 \fB\-underline\fR option.  In normal usage, pressing
  90 mouse button 1 over the menubutton causes the associated menu to
  91 be posted just underneath the menubutton.  If the mouse is moved over
  92 the menu before releasing the mouse button, the button release
  93 causes the underlying menu entry to be invoked.  When the button
  94 is released, the menu is unposted.
  95 .PP
  96 Menubuttons are used to construct a \fBtk_optionMenu\fR, which is the
  97 preferred mechanism for allowing a user to select one item from a list
  98 on Mac OS X.
  99 .PP
 100 Menubuttons were also typically organized into groups called menu bars
 101 that allow scanning:
 102 if the mouse button is pressed over one menubutton (causing it
 103 to post its menu) and the mouse is moved over another menubutton
 104 in the same menu bar without releasing the mouse button, then the
 105 menu of the first menubutton is unposted and the menu of the
 106 new menubutton is posted instead.
 107 \fIThis use is deprecated\fR in favor of setting a \fBmenu\fR directly as a
 108 menubar; see the \fBtoplevel\fR's \fB\-menu\fR option for how to do that.
 109 .PP
 110 There are several interactions between menubuttons and menus;  see
 111 the \fBmenu\fR manual entry for information on various menu configurations,
 112 such as pulldown menus and option menus.
 113 .SH "WIDGET COMMAND"
 114 .PP
 115 The \fBmenubutton\fR command creates a new Tcl command whose
 116 name is \fIpathName\fR.  This
 117 command may be used to invoke various
 118 operations on the widget.  It has the following general form:
 119 .CS
 120 \fIpathName option \fR?\fIarg arg ...\fR?
 121 .CE
 122 \fIOption\fR and the \fIarg\fRs
 123 determine the exact behavior of the command.  The following
 124 commands are possible for menubutton widgets:
 125 .TP
 126 \fIpathName \fBcget \fIoption\fR
 127 .
 128 Returns the current value of the configuration option given
 129 by \fIoption\fR.
 130 \fIOption\fR may have any of the values accepted by the \fBmenubutton\fR
 131 command.
 132 .TP
 133 \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR?
 134 .
 135 Query or modify the configuration options of the widget.
 136 If no \fIoption\fR is specified, returns a list describing all of
 137 the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for
 138 information on the format of this list).  If \fIoption\fR is specified
 139 with no \fIvalue\fR, then the command returns a list describing the
 140 one named option (this list will be identical to the corresponding
 141 sublist of the value returned if no \fIoption\fR is specified).  If
 142 one or more \fIoption\-value\fR pairs are specified, then the command
 143 modifies the given widget option(s) to have the given value(s);  in
 144 this case the command returns an empty string.
 145 \fIOption\fR may have any of the values accepted by the \fBmenubutton\fR
 146 command.
 147 .SH "DEFAULT BINDINGS"
 148 .PP
 149 Tk automatically creates class bindings for menubuttons that give them
 150 the following default behavior:
 151 .IP [1]
 152 A menubutton activates whenever the mouse passes over it and deactivates
 153 whenever the mouse leaves it.
 154 .IP [2]
 155 Pressing mouse button 1 over a menubutton posts the menubutton:
 156 its relief changes to raised and its associated menu is posted
 157 under the menubutton.  If the mouse is dragged down into the menu
 158 with the button still down, and if the mouse button is then
 159 released over an entry in the menu, the menubutton is unposted
 160 and the menu entry is invoked.
 161 .IP [3]
 162 If button 1 is pressed over a menubutton and then released over that
 163 menubutton, the menubutton stays posted: you can still move the mouse
 164 over the menu and click button 1 on an entry to invoke it.
 165 Once a menu entry has been invoked, the menubutton unposts itself.
 166 .IP [4]
 167 If button 1 is pressed over a menubutton and then dragged over some
 168 other menubutton, the original menubutton unposts itself and the
 169 new menubutton posts.
 170 .IP [5]
 171 If button 1 is pressed over a menubutton and released outside
 172 any menubutton or menu, the menubutton unposts without invoking
 173 any menu entry.
 174 .IP [6]
 175 When a menubutton is posted, its associated menu claims the input
 176 focus to allow keyboard traversal of the menu and its submenus.
 177 See the \fBmenu\fR manual entry for details on these bindings.
 178 .IP [7]
 179 If the \fB\-underline\fR option has been specified for a menubutton
 180 then keyboard traversal may be used to post the menubutton:
 181 Alt+\fIx\fR, where \fIx\fR is the underlined character (or its
 182 lower-case or upper-case equivalent), may be typed in any window
 183 under the menubutton's toplevel to post the menubutton.
 184 .IP [8]
 185 The F10 key may be typed in any window to post the first menubutton
 186 under its toplevel window that is not disabled.
 187 .IP [9]
 188 If a menubutton has the input focus, the space and return keys
 189 post the menubutton.
 190 .PP
 191 If the menubutton's state is \fBdisabled\fR then none of the above
 192 actions occur:  the menubutton is completely non-responsive.
 193 .PP
 194 The behavior of menubuttons can be changed by defining new bindings for
 195 individual widgets or by redefining the class bindings.
 196 .SH "SEE ALSO"
 197 ttk::menubutton(n), menu(n)
 198 .SH KEYWORDS
 199 menubutton, widget
 200 '\" Local Variables:
 201 '\" mode: nroff
 202 '\" End: