doc/menubutton.n

   1 '\"
   2 '\" Copyright (c) 1990-1994 The Regents of the University of California.
   3 '\" Copyright (c) 1994-1995 Sun Microsystems, Inc.
   4 '\" Copyright (c) 1996-1999 Christian Werner
   5 '\"
   6 '\" See the file "license.terms" for information on usage and redistribution
   7 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   8 '\"
   9 .so man.macros
  10 .TH menubutton n 8.0 Ck "Ck Built-In Commands"
  11 .BS
  12 '\" Note:  do not modify the .SH NAME line immediately below!
  13 .SH NAME
  14 menubutton \- Create and manipulate menubutton widgets
  15 .SH SYNOPSIS
  16 \fBmenubutton\fI \fIpathName \fR?\fIoptions\fR?
  17 .SH "STANDARD OPTIONS"
  18 .LP
  19 .nf
  20 .ta 3.8c 7.6c 11.4c
  21 \fBactiveAttributes\fR  \fBattributes\fR        \fBdisabledForeground\fR        \fBtextVariable\fR
  22 \fBactiveBackground\fR  \fBbackground\fR        \fBforeground\fR        \fBunderline\fR
  23 \fBactiveForeground\fR  \fBdisabledAttributes\fR        \fBtakeFocus\fR \fBunderlineAttributes\fR
  24 \fBanchor\fR    \fBdisabledBackground\fR        \fBtext\fR      \fBunderlineForeground\fR
  25 .fi
  26 .LP
  27 See the ``options'' manual entry for details on the standard options.
  28 .SH "WIDGET-SPECIFIC OPTIONS"
  29 .ta 4c
  30 .LP
  31 .nf
  32 Name:   \fBheight\fR
  33 Class:  \fBHeight\fR
  34 Command-Line Switch:    \fB\-height\fR
  35 .fi
  36 .IP
  37 Specifies a desired height for the menubutton in screen lines.
  38 If this option isn't specified, the menubutton's desired height is 1 line.
  39 .LP
  40 .nf
  41 Name:   \fBindicatorForeground\fR
  42 Class:  \fBIndicatorForeground\fR
  43 Command-Line Switch:    \fB\-indicatorforeground\fR
  44 .fi
  45 .IP
  46 Color in which the indicator rectangle, if any, is drawn.
  47 On color terminals this defaults to red, on monochrome terminals
  48 to white.
  49 .LP
  50 .nf
  51 Name:   \fBindicatorOn\fR
  52 Class:  \fBIndicatorOn\fR
  53 Command-Line Switch:    \fB\-indicatoron\fR
  54 .fi
  55 .IP
  56 The value must be a proper boolean value.  If it is true then
  57 a small indicator rectangle will be displayed on the right side
  58 of the menubutton and the default menu bindings will treat this
  59 as an option menubutton.  If false then no indicator will be
  60 displayed.
  61 .LP
  62 .nf
  63 Name:   \fBmenu\fR
  64 Class:  \fBMenuName\fR
  65 Command-Line Switch:    \fB\-menu\fR
  66 .fi
  67 .IP
  68 Specifies the path name of the menu associated with this menubutton.
  69 The menu must be a child of the menubutton.
  70 .LP
  71 .nf
  72 Name:   \fBstate\fR
  73 Class:  \fBState\fR
  74 Command-Line Switch:    \fB\-state\fR
  75 .fi
  76 .IP
  77 Specifies one of three states for the menubutton:  \fBnormal\fR, \fBactive\fR,
  78 or \fBdisabled\fR.  In normal state the menubutton is displayed using the
  79 \fBattributes\fR, \fBforeground\fR, and \fBbackground\fR options.
  80 The active state is typically used when the input focus is in the menubutton.
  81 In active state the menubutton is displayed using the
  82 \fBactiveAttributes\fR, \fBactiveForeground\fR, and
  83 \fBactiveBackground\fR options.
  84 Disabled state means that the menubutton should be insensitive:
  85 the default bindings will refuse to activate
  86 the widget and will ignore mouse button presses.
  87 In this state the \fBdisabledAttributes\fR, \fBdisabledForeground\fR, and
  88 \fBdisabledBackground\fR options determine how the button is displayed.
  89 .LP
  90 .nf
  91 Name:   \fBwidth\fR
  92 Class:  \fBWidth\fR
  93 Command-Line Switch:    \fB\-width\fR
  94 .fi
  95 .IP
  96 Specifies a desired width for the menubutton in screen columns.
  97 If this option isn't specified, the menubutton's desired width is computed
  98 from the size of the text being displayed in it.
  99 .BE
 100
 101 .SH INTRODUCTION
 102 .PP
 103 The \fBmenubutton\fR command creates a new window (given by the
 104 \fIpathName\fR argument) and makes it into a menubutton widget.
 105 Additional
 106 options, described above, may be specified on the command line
 107 or in the option database
 108 to configure aspects of the menubutton such as its colors, attributes,
 109 and text.  The \fBmenubutton\fR command returns its
 110 \fIpathName\fR argument.  At the time this command is invoked,
 111 there must not exist a window named \fIpathName\fR, but
 112 \fIpathName\fR's parent must exist.
 113 .PP
 114 A menubutton is a widget that displays a textual string
 115 and is associated with a menu widget.
 116 One of the characters may optionally be underlined using the
 117 \fBunderline\fR, \fBunderlineAttributes\fR, and
 118 \fBunderlineForeground\fR options.
 119 In normal usage, pressing mouse button 1 over the menubutton causes
 120 the associated menu to be posted just underneath the menubutton.
 121 .PP
 122 There are several interactions between menubuttons and menus;  see
 123 the \fBmenu\fR manual entry for information on various menu configurations,
 124 such as pulldown menus and option menus.
 125
 126 .SH "WIDGET COMMAND"
 127 .PP
 128 The \fBmenubutton\fR command creates a new Tcl command whose
 129 name is \fIpathName\fR.  This
 130 command may be used to invoke various
 131 operations on the widget.  It has the following general form:
 132 .DS C
 133 \fIpathName option \fR?\fIarg arg ...\fR?
 134 .DE
 135 \fIOption\fR and the \fIarg\fRs
 136 determine the exact behavior of the command.  The following
 137 commands are possible for menubutton widgets:
 138 .TP
 139 \fIpathName \fBcget\fR \fIoption\fR
 140 Returns the current value of the configuration option given
 141 by \fIoption\fR.
 142 \fIOption\fR may have any of the values accepted by the \fBmenubutton\fR
 143 command.
 144 .TP
 145 \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR?
 146 Query or modify the configuration options of the widget.
 147 If no \fIoption\fR is specified, returns a list describing all of
 148 the available options for \fIpathName\fR. If \fIoption\fR is specified
 149 with no \fIvalue\fR, then the command returns a list describing the
 150 one named option (this list will be identical to the corresponding
 151 sublist of the value returned if no \fIoption\fR is specified).  If
 152 one or more \fIoption\-value\fR pairs are specified, then the command
 153 modifies the given widget option(s) to have the given value(s);  in
 154 this case the command returns an empty string.
 155 \fIOption\fR may have any of the values accepted by the \fBmenubutton\fR
 156 command.
 157
 158 .SH "DEFAULT BINDINGS"
 159 .PP
 160 Ck automatically creates class bindings for menubuttons that give them
 161 the following default behavior:
 162 .IP [1]
 163 A menubutton activates whenever it gets the input focus and deactivates
 164 whenever it loses the input focus.
 165 .IP [2]
 166 Pressing mouse button 1 over a menubutton posts the menubutton:
 167 its associated menu is posted under the menubutton.
 168 Once a menu entry has been invoked, the menubutton unposts itself.
 169 .IP [3]
 170 When a menubutton is posted, its associated menu claims the input
 171 focus to allow keyboard traversal of the menu and its submenus.
 172 See the \fBmenu\fR manual entry for details on these bindings.
 173 .IP [4]
 174 The F10 key may be typed in any window to post the first menubutton
 175 under its toplevel window that isn't disabled.
 176 .IP [5]
 177 If a menubutton has the input focus, the space and return keys
 178 post the menubutton.
 179 .PP
 180 If the menubutton's state is \fBdisabled\fR then none of the above
 181 actions occur:  the menubutton is completely non-responsive.
 182 .PP
 183 The behavior of menubuttons can be changed by defining new bindings for
 184 individual widgets or by redefining the class bindings.
 185
 186 .SH KEYWORDS
 187 menubutton, widget