Pmw/Pmw_1_2/doc/ComboBox.html

   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.ComboBox 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.ComboBox</h1>
  13
  14 <center><IMG SRC=ComboBox.gif ALT="" WIDTH=376 HEIGHT=246></center>
  15 <dl>
  16 <dt> <h3>Name</h3></dt><dd>
  17 <p>Pmw.ComboBox() -
  18     dropdown or simple combination box
  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     A combobox contains an entry field and an associated scrolled
  29     listbox.  When an item in the listbox is selected, it is displayed
  30     in the entry field.  Optionally, the user may also edit the entry
  31     field directly.</p>
  32
  33 <p>    For a simple combobox, the scrolled listbox is displayed beneath
  34     the entry field.  For a dropdown combobox (the default), the
  35     scrolled listbox is displayed in a window which pops up beneath
  36     the entry field when the user clicks on an arrow button on the
  37     right of the entry field.  Either style allows an optional label.</p>
  38
  39 <p></p>
  40
  41
  42 </dd>
  43 <dt> <h3>Options</h3></dt><dd>
  44 Options for this megawidget and its base
  45 classes are described below.<p></p>
  46 <a name=option.autoclear></a>
  47 <dl><dt> <strong>autoclear
  48 </strong></dt><dd>
  49 Initialisation option. If both <strong>autoclear</strong> and <strong>history</strong> are true, clear the entry field
  50     whenever <strong>&lt;Return&gt;</strong> is pressed, after adding the value to the
  51     history list. The default is <strong>0</strong>.</p>
  52
  53
  54 </dd></dl>
  55 <a name=option.buttonaspect></a>
  56 <dl><dt> <strong>buttonaspect
  57 </strong></dt><dd>
  58 Initialisation option. The width of the arrow button as a proportion of the height.  The
  59     height of the arrow button is set to the height of the entry
  60     widget. The default is <strong>1.0</strong>.</p>
  61
  62
  63 </dd></dl>
  64 <a name=option.dropdown></a>
  65 <dl><dt> <strong>dropdown
  66 </strong></dt><dd>
  67 Initialisation option. Specifies whether the combobox should be dropdown or simple. The default is <strong>1</strong>.</p>
  68
  69
  70 </dd></dl>
  71 <a name=option.fliparrow></a>
  72 <dl><dt> <strong>fliparrow
  73 </strong></dt><dd>
  74 Initialisation option. If true, the arrow button is draw upside down when the listbox is
  75     being displayed.  Used only in dropdown megawidgets. The default is <strong>0</strong>.</p>
  76
  77
  78 </dd></dl>
  79 <a name=option.history></a>
  80 <dl><dt> <strong>history
  81 </strong></dt><dd>
  82 Initialisation option. When <strong>&lt;Return&gt;</strong> is pressed in the entry field, the current value
  83     of the entry field is appended to the listbox if <strong>history</strong> is
  84     true. The default is <strong>1</strong>.</p>
  85
  86
  87 </dd></dl>
  88 <a name=option.labelmargin></a>
  89 <dl><dt> <strong>labelmargin
  90 </strong></dt><dd>
  91 Initialisation option. If the <strong>labelpos</strong> option is not <strong>None</strong>, this specifies the
  92         distance between the <strong>label</strong> component and the rest of the
  93         megawidget. The default is <strong>0</strong>.</p>
  94
  95
  96 </dd></dl>
  97 <a name=option.labelpos></a>
  98 <dl><dt> <strong>labelpos
  99 </strong></dt><dd>
 100 Initialisation option. Specifies where to place the <strong>label</strong> component.  If not
 101         <strong>None</strong>, it should be a concatenation of one or two of the
 102         letters <strong>'n'</strong>, <strong>'s'</strong>, <strong>'e'</strong> and <strong>'w'</strong>.  The first letter
 103         specifies on which side of the megawidget to place the label.
 104         If a second letter is specified, it indicates where on that
 105         side to place the label.  For example, if <strong>labelpos</strong> is <strong>'w'</strong>,
 106         the label is placed in the center of the left hand side; if
 107         it is <strong>'wn'</strong>, the label is placed at the top of the left
 108         hand side; if it is <strong>'ws'</strong>, the label is placed at the
 109         bottom of the left hand side.</p>
 110 <p>        If <strong>None</strong>, a label component is not created. The default is <strong>None</strong>.</p>
 111
 112
 113
 114 </dd></dl>
 115 <a name=option.listheight></a>
 116 <dl><dt> <strong>listheight
 117 </strong></dt><dd>
 118 Initialisation option. The height, in pixels, of the dropdown listbox. The default is <strong>200</strong>.</p>
 119
 120
 121 </dd></dl>
 122 <a name=option.selectioncommand></a>
 123 <dl><dt> <strong>selectioncommand
 124 </strong></dt><dd>
 125 The function to call when an item is selected.
 126     If this function takes a long time to run, and you want the entry
 127     field to be updated quickly, call <code>update_idletasks()</code> at the
 128     beginning of the function.  Alternatively, wrap the function using
 129     <code>Pmw.busycallback()</code>. The default is <strong>None</strong>.</p>
 130
 131
 132 </dd></dl>
 133 <a name=option.sticky></a>
 134 <dl><dt> <strong>sticky
 135 </strong></dt><dd>
 136 Initialisation option.  The default is <strong>'ew'</strong>.</p>
 137
 138
 139 </dd></dl>
 140 <a name=option.unique></a>
 141 <dl><dt> <strong>unique
 142 </strong></dt><dd>
 143 Initialisation option. If both <strong>unique</strong> and <strong>history</strong> are true, the current value of the
 144     entry field is not added to the listbox if it is already in the
 145     list. The default is <strong>1</strong>.</p>
 146
 147
 148 </dd></dl>
 149 </dd>
 150 <dt> <h3>Components</h3></dt><dd>
 151 Components created by this megawidget and its base
 152 classes are described below.<p></p>
 153 <a name=component.arrowbutton></a>
 154 <dl><dt> <strong>arrowbutton
 155 </strong></dt><dd>
 156 In a dropdown combobox, the button to popup the listbox. By default, this component is a Tkinter.Canvas.</p>
 157
 158
 159 </dd></dl>
 160 <a name=component.entryfield></a>
 161 <dl><dt> <strong>entryfield
 162 </strong></dt><dd>
 163 The entry field where the current selection is displayed. By default, this component is a <a href="EntryField.html">Pmw.EntryField</a>.</p>
 164
 165
 166 </dd></dl>
 167 <a name=component.hull></a>
 168 <dl><dt> <strong>hull
 169 </strong></dt><dd>
 170 This acts as the body for the entire megawidget.  Other components
 171     are created as children of the hull to further specialise this
 172     class. By default, this component is a Tkinter.Frame.</p>
 173
 174
 175 </dd></dl>
 176 <a name=component.label></a>
 177 <dl><dt> <strong>label
 178 </strong></dt><dd>
 179 If the <strong>labelpos</strong> option is not <strong>None</strong>, this component is
 180         created as a text label for the megawidget.  See the
 181         <strong>labelpos</strong> option for details.  Note that to set, for example,
 182         the <strong>text</strong> option of the label, you need to use the <strong>label_text</strong>
 183         component option. By default, this component is a Tkinter.Label.</p>
 184
 185
 186 </dd></dl>
 187 <a name=component.popup></a>
 188 <dl><dt> <strong>popup
 189 </strong></dt><dd>
 190 In a dropdown combobox, the dropdown window. By default, this component is a Tkinter.Toplevel.</p>
 191
 192
 193 </dd></dl>
 194 <a name=component.scrolledlist></a>
 195 <dl><dt> <strong>scrolledlist
 196 </strong></dt><dd>
 197 The scrolled listbox which displays the items to select. By default, this component is a <a href="ScrolledListBox.html">Pmw.ScrolledListBox</a>.</p>
 198
 199
 200 </dd></dl>
 201 </dd>
 202 <dt> <h3>Component aliases</h3></dt><dd>
 203 Sub-components of components of this megawidget
 204 may be accessed via the following aliases.<p></p>
 205 <dl><dt> <strong>entry
 206 </strong></dt><dd>
 207 Alias for <strong>entryfield_entry</strong>.
 208 </dd></dl>
 209 <dl><dt> <strong>listbox
 210 </strong></dt><dd>
 211 Alias for <strong>scrolledlist_listbox</strong>.
 212 </dd></dl>
 213 </dd>
 214 <a name=methods></a>
 215 <dt> <h3>Methods</h3></dt><dd>
 216 Only methods specific to this megawidget are described below.
 217 For a description of its inherited methods, see the
 218 manual for its base class
 219 <strong><a href="MegaWidget.html#methods">Pmw.MegaWidget</a></strong>.
 220 In addition, methods from the following classes
 221 are forwarded by this megawidget.
 222 Methods from <strong><a href="ScrolledListBox.html#methods">Pmw.ScrolledListBox</a></strong>
 223 are forwarded to the
 224 <strong>scrolledlist</strong> component.
 225 Methods from <strong><a href="EntryField.html#methods">Pmw.EntryField</a></strong>
 226 are forwarded to the
 227 <strong>entryfield</strong> component.
 228 Forwarded methods are searched in the order given.
 229 <p></p>
 230 <a name=method.bbox></a>
 231 <dl><dt> <strong>bbox</strong>(<em>index</em>)</dt><dd>
 232 This method is explicitly forwarded to the <strong>scrolledlist</strong>
 233     component's <code>bbox()</code> method.  Without this explicit forwarding,
 234     the <code>bbox()</code> method (aliased to <code>grid_bbox()</code>) of the <strong>hull</strong> would
 235     be invoked, which is probably not what the programmer intended.</p>
 236
 237
 238 </dd></dl>
 239 <a name=method.clear></a>
 240 <dl><dt> <strong>clear</strong>()</dt><dd>
 241 Delete all items from the scrolled listbox and delete all text
 242     from the entry widget.</p>
 243
 244
 245 </dd></dl>
 246 <a name=method.get></a>
 247 <dl><dt> <strong>get</strong>(<em>first</em> = <strong>None</strong>, <em>last</em> = <strong>None</strong>)</dt><dd>
 248 This is the same as the <code>get()</code> method of the <strong>scrolledlist</strong>
 249     component, except that if <em>first</em> is <strong>None</strong> then
 250     the value of the entry field is returned.</p>
 251
 252
 253 </dd></dl>
 254 <a name=method.invoke></a>
 255 <dl><dt> <strong>invoke</strong>()</dt><dd>
 256 If a dropdown combobox, display the dropdown listbox.  In a simple
 257     combobox, select the currently selected item in the listbox,
 258     call the <strong>selectioncommand</strong> and return the result.</p>
 259
 260
 261 </dd></dl>
 262 <a name=method.selectitem></a>
 263 <dl><dt> <strong>selectitem</strong>(<em>index</em>, <em>setentry</em> = <strong>1</strong>)</dt><dd>
 264 Select the item in the listbox specified by <em>index</em> which may be
 265     either one of the items in the listbox or the integer index of one
 266     of the items in the listbox.</p>
 267 <p>    If <em>setentry</em> is true, also set the entry field to the selected
 268     item.</p>
 269
 270
 271
 272 </dd></dl>
 273 <a name=method.size></a>
 274 <dl><dt> <strong>size</strong>()</dt><dd>
 275 This method is explicitly forwarded to the <strong>scrolledlist</strong>
 276     component's <code>size()</code> method.  Without this explicit forwarding,
 277     the <code>size()</code> method (aliased to <code>grid_size()</code>) of the <strong>hull</strong> would
 278     be invoked, which is probably not what the programmer intended.</p>
 279
 280
 281 </dd></dl>
 282 </dd>
 283 <dt> <h3>Example</h3></dt><dd>
 284 The image at the top of this manual is a snapshot
 285 of the window (or part of the window) produced
 286 by the following code.<p></p>
 287 <pre>
 288 class Demo:
 289     def __init__(self, parent):
 290         parent.configure(background = 'white')
 291
 292         # Create and pack the widget to be configured.
 293         self.target = Tkinter.Label(parent,
 294                 relief = 'sunken',
 295                 padx = 20,
 296                 pady = 20,
 297         )
 298         self.target.pack(fill = 'x', padx = 8, pady = 8)
 299
 300         # Create and pack the simple ComboBox.
 301         words = ('Monti', 'Python', 'ik', 'den', 'Holie', 'Grailen', '(Bok)')
 302         simple = Pmw.ComboBox(parent,
 303                 label_text = 'Simple ComboBox:',
 304                 labelpos = 'nw',
 305                 selectioncommand = self.changeText,
 306                 scrolledlist_items = words,
 307                 dropdown = 0,
 308         )
 309         simple.pack(side = 'left', fill = 'both',
 310                 expand = 1, padx = 8, pady = 8)
 311
 312         # Display the first text.
 313         first = words[0]
 314         simple.selectitem(first)
 315         self.changeText(first)
 316
 317         # Create and pack the dropdown ComboBox.
 318         colours = ('cornsilk1', 'snow1', 'seashell1', 'antiquewhite1',
 319                 'bisque1', 'peachpuff1', 'navajowhite1', 'lemonchiffon1',
 320                 'ivory1', 'honeydew1', 'lavenderblush1', 'mistyrose1')
 321         dropdown = Pmw.ComboBox(parent,
 322                 label_text = 'Dropdown ComboBox:',
 323                 labelpos = 'nw',
 324                 selectioncommand = self.changeColour,
 325                 scrolledlist_items = colours,
 326         )
 327         dropdown.pack(side = 'left', anchor = 'n',
 328                 fill = 'x', expand = 1, padx = 8, pady = 8)
 329
 330         # Display the first colour.
 331         first = colours[0]
 332         dropdown.selectitem(first)
 333         self.changeColour(first)
 334
 335     def changeColour(self, colour):
 336         print 'Colour: ' + colour
 337         self.target.configure(background = colour)
 338
 339     def changeText(self, text):
 340         print 'Text: ' + text
 341         self.target.configure(text = text)
 342
 343 </pre>
 344 </dd>
 345 </dl>
 346
 347     <center><P ALIGN="CENTER">
 348     <IMG SRC = blue_line.gif ALT = "" WIDTH=320 HEIGHT=5>
 349     </p></center>
 350
 351
 352     <font size=-1>
 353     <center><P ALIGN="CENTER">
 354     Pmw 1.2 -
 355      5 Aug 2003
 356      - <a href="index.html">Home</a>
 357     <br>Manual page last reviewed: 1 November 1998
 358     </p></center>
 359     </font>
 360
 361     </body>
 362     </html>
 363