| 1 | |
| 2 | <html> |
| 3 | <head> |
| 4 | <meta name="description" content="Pmw - a toolkit for building high-level compound widgets in Python"> |
| 5 | <meta name="content" content="python, megawidget, mega widget, compound widget, gui, tkinter"> |
| 6 | <title>Pmw.OptionMenu reference manual</title> |
| 7 | </head> |
| 8 | |
| 9 | <body bgcolor="#ffffff" text="#000000" link="#0000ee" |
| 10 | vlink="551a8b" alink="ff0000"> |
| 11 | |
| 12 | <h1 ALIGN="CENTER">Pmw.OptionMenu</h1> |
| 13 | |
| 14 | <center><IMG SRC=OptionMenu.gif ALT="" WIDTH=298 HEIGHT=170></center> |
| 15 | <dl> |
| 16 | <dt> <h3>Name</h3></dt><dd> |
| 17 | <p>Pmw.OptionMenu() - |
| 18 | single item selection megawidget |
| 19 | </p> |
| 20 | |
| 21 | |
| 22 | </dd> |
| 23 | <dt> <h3>Inherits</h3></dt><dd> |
| 24 | <a href="MegaWidget.html">Pmw.MegaWidget</a><br> |
| 25 | </dd> |
| 26 | <dt> <h3>Description</h3></dt><dd> |
| 27 | <p> |
| 28 | An option menu consists of a menu button |
| 29 | and an associated menu which pops up when the button is pressed. |
| 30 | The text displayed in the menu button is updated whenever an item |
| 31 | is selected in the menu. The currently selected value can be |
| 32 | retrieved from the megawidget.</p> |
| 33 | |
| 34 | <p></p> |
| 35 | |
| 36 | |
| 37 | </dd> |
| 38 | <dt> <h3>Options</h3></dt><dd> |
| 39 | Options for this megawidget and its base |
| 40 | classes are described below.<p></p> |
| 41 | <a name=option.command></a> |
| 42 | <dl><dt> <strong>command |
| 43 | </strong></dt><dd> |
| 44 | Specifies a function to call whenever a menu item is selected or |
| 45 | the <code>invoke()</code> method is called. The function is called with the |
| 46 | currently selected value as its single argument. The default is <strong>None</strong>.</p> |
| 47 | |
| 48 | |
| 49 | </dd></dl> |
| 50 | <a name=option.initialitem></a> |
| 51 | <dl><dt> <strong>initialitem |
| 52 | </strong></dt><dd> |
| 53 | Initialisation option. Specifies the initial selected value. This option is treated in |
| 54 | the same way as the <em>index</em> argument of the <code>setitems()</code> method. The default is <strong>None</strong>.</p> |
| 55 | |
| 56 | |
| 57 | </dd></dl> |
| 58 | <a name=option.items></a> |
| 59 | <dl><dt> <strong>items |
| 60 | </strong></dt><dd> |
| 61 | Initialisation option. A sequence of strings containing the initial items to be displayed |
| 62 | in the <strong>menu</strong> component. The default is <strong>()</strong>.</p> |
| 63 | |
| 64 | |
| 65 | </dd></dl> |
| 66 | <a name=option.labelmargin></a> |
| 67 | <dl><dt> <strong>labelmargin |
| 68 | </strong></dt><dd> |
| 69 | Initialisation option. If the <strong>labelpos</strong> option is not <strong>None</strong>, this specifies the |
| 70 | distance between the <strong>label</strong> component and the rest of the |
| 71 | megawidget. The default is <strong>0</strong>.</p> |
| 72 | |
| 73 | |
| 74 | </dd></dl> |
| 75 | <a name=option.labelpos></a> |
| 76 | <dl><dt> <strong>labelpos |
| 77 | </strong></dt><dd> |
| 78 | Initialisation option. Specifies where to place the <strong>label</strong> component. If not |
| 79 | <strong>None</strong>, it should be a concatenation of one or two of the |
| 80 | letters <strong>'n'</strong>, <strong>'s'</strong>, <strong>'e'</strong> and <strong>'w'</strong>. The first letter |
| 81 | specifies on which side of the megawidget to place the label. |
| 82 | If a second letter is specified, it indicates where on that |
| 83 | side to place the label. For example, if <strong>labelpos</strong> is <strong>'w'</strong>, |
| 84 | the label is placed in the center of the left hand side; if |
| 85 | it is <strong>'wn'</strong>, the label is placed at the top of the left |
| 86 | hand side; if it is <strong>'ws'</strong>, the label is placed at the |
| 87 | bottom of the left hand side.</p> |
| 88 | <p> If <strong>None</strong>, a label component is not created. The default is <strong>None</strong>.</p> |
| 89 | |
| 90 | |
| 91 | |
| 92 | </dd></dl> |
| 93 | <a name=option.sticky></a> |
| 94 | <dl><dt> <strong>sticky |
| 95 | </strong></dt><dd> |
| 96 | Initialisation option. The default is <strong>'ew'</strong>.</p> |
| 97 | |
| 98 | |
| 99 | </dd></dl> |
| 100 | </dd> |
| 101 | <dt> <h3>Components</h3></dt><dd> |
| 102 | Components created by this megawidget and its base |
| 103 | classes are described below.<p></p> |
| 104 | <a name=component.hull></a> |
| 105 | <dl><dt> <strong>hull |
| 106 | </strong></dt><dd> |
| 107 | This acts as the body for the entire megawidget. Other components |
| 108 | are created as children of the hull to further specialise this |
| 109 | class. By default, this component is a Tkinter.Frame.</p> |
| 110 | |
| 111 | |
| 112 | </dd></dl> |
| 113 | <a name=component.label></a> |
| 114 | <dl><dt> <strong>label |
| 115 | </strong></dt><dd> |
| 116 | If the <strong>labelpos</strong> option is not <strong>None</strong>, this component is |
| 117 | created as a text label for the megawidget. See the |
| 118 | <strong>labelpos</strong> option for details. Note that to set, for example, |
| 119 | the <strong>text</strong> option of the label, you need to use the <strong>label_text</strong> |
| 120 | component option. By default, this component is a Tkinter.Label.</p> |
| 121 | |
| 122 | |
| 123 | </dd></dl> |
| 124 | <a name=component.menu></a> |
| 125 | <dl><dt> <strong>menu |
| 126 | </strong></dt><dd> |
| 127 | The popup menu displayed when the <strong>menubutton</strong> is pressed. By default, this component is a Tkinter.Menu.</p> |
| 128 | |
| 129 | |
| 130 | </dd></dl> |
| 131 | <a name=component.menubutton></a> |
| 132 | <dl><dt> <strong>menubutton |
| 133 | </strong></dt><dd> |
| 134 | The menu button displaying the currently selected value. By default, this component is a Tkinter.Menubutton.</p> |
| 135 | |
| 136 | |
| 137 | </dd></dl> |
| 138 | </dd> |
| 139 | <a name=methods></a> |
| 140 | <dt> <h3>Methods</h3></dt><dd> |
| 141 | Only methods specific to this megawidget are described below. |
| 142 | For a description of its inherited methods, see the |
| 143 | manual for its base class |
| 144 | <strong><a href="MegaWidget.html#methods">Pmw.MegaWidget</a></strong>. |
| 145 | <p></p> |
| 146 | <a name=method.getcurselection></a> |
| 147 | <dl><dt> <strong>getcurselection</strong>()</dt><dd> |
| 148 | Same as <code>getvalue()</code> method.</p> |
| 149 | |
| 150 | |
| 151 | </dd></dl> |
| 152 | <a name=method.getvalue></a> |
| 153 | <dl><dt> <strong>getvalue</strong>()</dt><dd> |
| 154 | Return the currently selected value.</p> |
| 155 | |
| 156 | |
| 157 | </dd></dl> |
| 158 | <a name=method.index></a> |
| 159 | <dl><dt> <strong>index</strong>(<em>index</em>)</dt><dd> |
| 160 | Return the numerical index of the menu item corresponding to |
| 161 | <em>index</em>. This may be specified in any of the following forms:</p> |
| 162 | <dl><dt><em>name</em></dt><dd>Specifies the menu item labelled <em>name</em>.<p></p> |
| 163 | |
| 164 | </dd> |
| 165 | <dt><em>number</em></dt><dd>Specifies the menu item numerically, where <strong>0</strong> corresponds to |
| 166 | the first menu item.<p></p> |
| 167 | |
| 168 | </dd> |
| 169 | <dt><strong>Pmw.END</strong></dt><dd>Specifies the last menu item.<p></p> |
| 170 | |
| 171 | </dd> |
| 172 | <dt><strong>Pmw.SELECT</strong></dt><dd>Specifies the currently selected menu item.<p></p> |
| 173 | |
| 174 | </dd></dl> |
| 175 | |
| 176 | |
| 177 | </dd></dl> |
| 178 | <a name=method.invoke></a> |
| 179 | <dl><dt> <strong>invoke</strong>(<em>index</em> = <strong>Pmw.SELECT</strong>)</dt><dd> |
| 180 | Calling this method is the same as selecting the menu item |
| 181 | specified by <em>index</em>: the text displayed by the |
| 182 | <strong>menubutton</strong> component is updated and the function specified by |
| 183 | the <strong>command</strong> option is called. <em>index</em> may have any of the |
| 184 | forms accepted by the <code>index()</code> method. The value returned by |
| 185 | <strong>command</strong> is returned.</p> |
| 186 | |
| 187 | |
| 188 | </dd></dl> |
| 189 | <a name=method.setitems></a> |
| 190 | <dl><dt> <strong>setitems</strong>(<em>items</em>, <em>index</em> = <strong>None</strong>)</dt><dd> |
| 191 | Replace all the items in the <strong>menu</strong> component with those specified |
| 192 | by <em>items</em>, which must be a sequence of strings.</p> |
| 193 | <p> If <em>index</em> is not <strong>None</strong>, set the selected value to <em>index</em>, which |
| 194 | may have any of the forms accepted by the <code>index()</code> method.</p> |
| 195 | |
| 196 | <p> If <em>index</em> is <strong>None</strong> and the <strong>textvariable</strong> option of the |
| 197 | <strong>menubutton</strong> component is the empty string, then if |
| 198 | the previous selected value is one of the <em>items</em>, then do not |
| 199 | change the selection. If the previous selected value is no longer |
| 200 | in <em>items</em>, then set the selected value to the first value in |
| 201 | <em>items</em>. If <em>items</em> is empty, set the selected value to the empty |
| 202 | string.</p> |
| 203 | |
| 204 | <p> If <em>index</em> is <strong>None</strong> and the <strong>textvariable</strong> option of the |
| 205 | <strong>menubutton</strong> component is not the empty string, then do not set |
| 206 | the selected value. This assumes that the variable is already (or |
| 207 | will be) set to the desired value.</p> |
| 208 | |
| 209 | |
| 210 | |
| 211 | </dd></dl> |
| 212 | <a name=method.setvalue></a> |
| 213 | <dl><dt> <strong>setvalue</strong>(<em>text</em>)</dt><dd> |
| 214 | Set the text displayed by the <strong>menubutton</strong> component to <em>text</em>.</p> |
| 215 | |
| 216 | |
| 217 | </dd></dl> |
| 218 | </dd> |
| 219 | <dt> <h3>Example</h3></dt><dd> |
| 220 | The image at the top of this manual is a snapshot |
| 221 | of the window (or part of the window) produced |
| 222 | by the following code.<p></p> |
| 223 | <pre> |
| 224 | class Demo: |
| 225 | def __init__(self, parent): |
| 226 | # Create and pack the OptionMenu megawidgets. |
| 227 | # The first one has a textvariable. |
| 228 | self.var = Tkinter.StringVar() |
| 229 | self.var.set('steamed') |
| 230 | self.method_menu = Pmw.OptionMenu(parent, |
| 231 | labelpos = 'w', |
| 232 | label_text = 'Choose method:', |
| 233 | menubutton_textvariable = self.var, |
| 234 | items = ['baked', 'steamed', 'stir fried', 'boiled', 'raw'], |
| 235 | menubutton_width = 10, |
| 236 | ) |
| 237 | self.method_menu.pack(anchor = 'w', padx = 10, pady = 10) |
| 238 | |
| 239 | self.vege_menu = Pmw.OptionMenu (parent, |
| 240 | labelpos = 'w', |
| 241 | label_text = 'Choose vegetable:', |
| 242 | items = ('broccoli', 'peas', 'carrots', 'pumpkin'), |
| 243 | menubutton_width = 10, |
| 244 | command = self._printOrder, |
| 245 | ) |
| 246 | self.vege_menu.pack(anchor = 'w', padx = 10, pady = 10) |
| 247 | |
| 248 | self.direction_menu = Pmw.OptionMenu (parent, |
| 249 | labelpos = 'w', |
| 250 | label_text = 'Menu direction:', |
| 251 | items = ('flush', 'above', 'below', 'left', 'right'), |
| 252 | menubutton_width = 10, |
| 253 | command = self._changeDirection, |
| 254 | ) |
| 255 | self.direction_menu.pack(anchor = 'w', padx = 10, pady = 10) |
| 256 | |
| 257 | menus = (self.method_menu, self.vege_menu, self.direction_menu) |
| 258 | Pmw.alignlabels(menus) |
| 259 | |
| 260 | def _printOrder(self, vege): |
| 261 | # Can use 'self.var.get()' instead of 'getcurselection()'. |
| 262 | print 'You have chosen %s %s.' % \ |
| 263 | (self.method_menu.getcurselection(), vege) |
| 264 | |
| 265 | def _changeDirection(self, direction): |
| 266 | for menu in (self.method_menu, self.vege_menu, self.direction_menu): |
| 267 | menu.configure(menubutton_direction = direction) |
| 268 | |
| 269 | </pre> |
| 270 | </dd> |
| 271 | </dl> |
| 272 | |
| 273 | <center><P ALIGN="CENTER"> |
| 274 | <IMG SRC = blue_line.gif ALT = "" WIDTH=320 HEIGHT=5> |
| 275 | </p></center> |
| 276 | |
| 277 | |
| 278 | <font size=-1> |
| 279 | <center><P ALIGN="CENTER"> |
| 280 | Pmw 1.2 - |
| 281 | 5 Aug 2003 |
| 282 | - <a href="index.html">Home</a> |
| 283 | <br>Manual page last reviewed: 23 October 1998 |
| 284 | </p></center> |
| 285 | </font> |
| 286 | |
| 287 | </body> |
| 288 | </html> |
| 289 | |