Pmw/Pmw_1_2/doc/SelectionDialog.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.SelectionDialog 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.SelectionDialog</h1>
  13
  14 <center><IMG SRC=SelectionDialog.gif ALT="" WIDTH=206 HEIGHT=278></center>
  15 <dl>
  16 <dt> <h3>Name</h3></dt><dd>
  17 <p>Pmw.SelectionDialog() -
  18     selection dialog displaying a scrolled list
  19 </p>
  20
  21
  22 </dd>
  23 <dt> <h3>Inherits</h3></dt><dd>
  24 <a href="Dialog.html">Pmw.Dialog</a><br>
  25 </dd>
  26 <dt> <h3>Description</h3></dt><dd>
  27 <p>
  28     The selection dialog is a dialog window which displays a scrolled
  29     list which can be used to prompt the user for a value.</p>
  30
  31 <p></p>
  32
  33
  34 </dd>
  35 <dt> <h3>Options</h3></dt><dd>
  36 Options for this megawidget and its base
  37 classes are described below.<p></p>
  38 <a name=option.activatecommand></a>
  39 <dl><dt> <strong>activatecommand
  40 </strong></dt><dd>
  41 If this is callable, it will be called whenever the megawidget is
  42     activated by a call to <code>activate()</code>. The default is <strong>None</strong>.</p>
  43
  44
  45 </dd></dl>
  46 <a name=option.borderx></a>
  47 <dl><dt> <strong>borderx
  48 </strong></dt><dd>
  49 Initialisation option. The padding to the left and right of the scrolled list. The default is <strong>10</strong>.</p>
  50
  51
  52 </dd></dl>
  53 <a name=option.bordery></a>
  54 <dl><dt> <strong>bordery
  55 </strong></dt><dd>
  56 Initialisation option. The padding above and below the scrolled list. The default is <strong>10</strong>.</p>
  57
  58
  59 </dd></dl>
  60 <a name=option.buttonboxpos></a>
  61 <dl><dt> <strong>buttonboxpos
  62 </strong></dt><dd>
  63 Initialisation option. Specifies on which side of the dialog window to place the button
  64     box.  Must be one of <strong>'n'</strong>, <strong>'s'</strong>, <strong>'e'</strong> or <strong>'w'</strong>. The default is <strong>'s'</strong>.</p>
  65
  66
  67 </dd></dl>
  68 <a name=option.buttons></a>
  69 <dl><dt> <strong>buttons
  70 </strong></dt><dd>
  71 This must be a tuple or a list and specifies the names on the
  72     buttons in the button box. The default is <strong>('OK',)</strong>.</p>
  73
  74
  75 </dd></dl>
  76 <a name=option.command></a>
  77 <dl><dt> <strong>command
  78 </strong></dt><dd>
  79 Specifies a function to call whenever a button in the button box
  80     is invoked or the window is deleted by the window manager.  The
  81     function is called with a single argument, which is the name of
  82     the button which was invoked, or <strong>None</strong> if the window was deleted
  83     by the window manager.</p>
  84 <p>    If the value of <strong>command</strong> is not callable, the default behaviour
  85     is to deactivate the window if it is active, or withdraw the
  86     window if it is not active.  If it is deactivated, <code>deactivate()</code>
  87     is called with the button name or <strong>None</strong> as described above. The default is <strong>None</strong>.</p>
  88
  89
  90
  91 </dd></dl>
  92 <a name=option.deactivatecommand></a>
  93 <dl><dt> <strong>deactivatecommand
  94 </strong></dt><dd>
  95 If this is callable, it will be called whenever the megawidget is
  96     deactivated by a call to <code>deactivate()</code>. The default is <strong>None</strong>.</p>
  97
  98
  99 </dd></dl>
 100 <a name=option.defaultbutton></a>
 101 <dl><dt> <strong>defaultbutton
 102 </strong></dt><dd>
 103 Specifies the default button in the button box.  If the <strong>&lt;Return&gt;</strong>
 104     key is hit when the dialog has focus, the default button will be
 105     invoked.  If <strong>defaultbutton</strong> is <strong>None</strong>, there will be no default
 106     button and hitting the <strong>&lt;Return&gt;</strong> key will have no effect. The default is <strong>None</strong>.</p>
 107
 108
 109 </dd></dl>
 110 <a name=option.master></a>
 111 <dl><dt> <strong>master
 112 </strong></dt><dd>
 113 This is used by the <code>activate()</code> method to control whether the
 114     window is made <em>transient</em> during modal dialogs.  See the
 115     <code>activate()</code> method. The default is <strong>'parent'</strong>.</p>
 116
 117
 118 </dd></dl>
 119 <a name=option.separatorwidth></a>
 120 <dl><dt> <strong>separatorwidth
 121 </strong></dt><dd>
 122 Initialisation option. If this is greater than <strong>0</strong>, a separator line with the specified
 123     width will be created between the button box and the child site,
 124     as a component named <strong>separator</strong>.  Since the default border of the
 125     button box and child site is <strong>raised</strong>, this option does not
 126     usually need to be set for there to be a visual separation between
 127     the button box and child site. The default is <strong>0</strong>.</p>
 128
 129
 130 </dd></dl>
 131 <a name=option.title></a>
 132 <dl><dt> <strong>title
 133 </strong></dt><dd>
 134 This is the title that the window manager displays in the title
 135     bar of the window. The default is <strong>None</strong>.</p>
 136
 137
 138 </dd></dl>
 139 </dd>
 140 <dt> <h3>Components</h3></dt><dd>
 141 Components created by this megawidget and its base
 142 classes are described below.<p></p>
 143 <a name=component.buttonbox></a>
 144 <dl><dt> <strong>buttonbox
 145 </strong></dt><dd>
 146 This is the button box containing the buttons for the dialog.  By
 147     default it is created with the options
 148     <code>(hull_borderwidth = 1, hull_relief = 'raised')</code>. By default, this component is a <a href="ButtonBox.html">Pmw.ButtonBox</a>.</p>
 149
 150
 151 </dd></dl>
 152 <a name=component.dialogchildsite></a>
 153 <dl><dt> <strong>dialogchildsite
 154 </strong></dt><dd>
 155 This is the child site for the dialog, which may be used to
 156     specialise the megawidget by creating other widgets within it.  By
 157     default it is created with the options
 158     <code>(borderwidth = 1, relief = 'raised')</code>. By default, this component is a Tkinter.Frame.</p>
 159
 160
 161 </dd></dl>
 162 <a name=component.hull></a>
 163 <dl><dt> <strong>hull
 164 </strong></dt><dd>
 165 This acts as the body for the entire megawidget.  Other components
 166     are created as children of the hull to further specialise this
 167     class. By default, this component is a Tkinter.Toplevel.</p>
 168
 169
 170 </dd></dl>
 171 <a name=component.scrolledlist></a>
 172 <dl><dt> <strong>scrolledlist
 173 </strong></dt><dd>
 174 The scrolled list for the user to enter a value. By default, this component is a <a href="ScrolledListBox.html">Pmw.ScrolledListBox</a>.</p>
 175
 176
 177 </dd></dl>
 178 <a name=component.separator></a>
 179 <dl><dt> <strong>separator
 180 </strong></dt><dd>
 181 If the <strong>separatorwidth</strong> initialisation option is non-zero, the
 182     <strong>separator</strong> component is the line dividing the area between the
 183     button box and the child site. By default, this component is a Tkinter.Frame.</p>
 184
 185
 186 </dd></dl>
 187 </dd>
 188 <dt> <h3>Component aliases</h3></dt><dd>
 189 Sub-components of components of this megawidget
 190 may be accessed via the following aliases.<p></p>
 191 <dl><dt> <strong>label
 192 </strong></dt><dd>
 193 Alias for <strong>scrolledlist_label</strong>.
 194 </dd></dl>
 195 <dl><dt> <strong>listbox
 196 </strong></dt><dd>
 197 Alias for <strong>scrolledlist_listbox</strong>.
 198 </dd></dl>
 199 </dd>
 200 <a name=methods></a>
 201 <dt> <h3>Methods</h3></dt><dd>
 202 Only methods specific to this megawidget are described below.
 203 For a description of its inherited methods, see the
 204 manual for its base class
 205 <strong><a href="Dialog.html#methods">Pmw.Dialog</a></strong>.
 206 In addition, methods from the
 207 <strong><a href="ScrolledListBox.html#methods">Pmw.ScrolledListBox</a></strong> class
 208 are forwarded by this megawidget to the
 209 <strong>scrolledlist</strong> component.
 210 <p></p>
 211 <a name=method.bbox></a>
 212 <dl><dt> <strong>bbox</strong>(<em>index</em>)</dt><dd>
 213 This method is explicitly forwarded to the <strong>listbox</strong> component's
 214     <code>bbox()</code> method.  Without this explicit forwarding, the <code>bbox()</code>
 215     method (aliased to <code>grid_bbox()</code>) of the <strong>hull</strong> would be invoked,
 216     which is probably not what the programmer intended.</p>
 217
 218
 219 </dd></dl>
 220 <a name=method.size></a>
 221 <dl><dt> <strong>size</strong>()</dt><dd>
 222 This method is explicitly forwarded to the <strong>listbox</strong> component's
 223     <code>size()</code> method.  Without this explicit forwarding, the <code>size()</code>
 224     method (aliased to <code>grid_size()</code>) of the <strong>hull</strong> would be invoked,
 225     which is probably not what the programmer intended.</p>
 226
 227
 228 </dd></dl>
 229 </dd>
 230 <dt> <h3>Example</h3></dt><dd>
 231 The image at the top of this manual is a snapshot
 232 of the window (or part of the window) produced
 233 by the following code.<p></p>
 234 <pre>
 235 class Demo:
 236     def __init__(self, parent):
 237         # Create the dialog.
 238         self.dialog = Pmw.SelectionDialog(parent,
 239             title = 'My SelectionDialog',
 240             buttons = ('OK', 'Cancel'),
 241             defaultbutton = 'OK',
 242             scrolledlist_labelpos = 'n',
 243             label_text = 'What do you think of Pmw?',
 244             scrolledlist_items = ('Cool man', 'Cool', 'Good', 'Bad', 'Gross'),
 245             command = self.execute)
 246         self.dialog.withdraw()
 247
 248         # Create button to launch the dialog.
 249         w = Tkinter.Button(parent, text = 'Show selection dialog',
 250                 command = self.dialog.activate)
 251         w.pack(padx = 8, pady = 8)
 252
 253     def execute(self, result):
 254         sels = self.dialog.getcurselection()
 255         if len(sels) == 0:
 256             print 'You clicked on', result, '(no selection)'
 257         else:
 258             print 'You clicked on', result, sels[0]
 259         self.dialog.deactivate(result)
 260
 261 </pre>
 262 </dd>
 263 </dl>
 264
 265     <center><P ALIGN="CENTER">
 266     <IMG SRC = blue_line.gif ALT = "" WIDTH=320 HEIGHT=5>
 267     </p></center>
 268
 269
 270     <font size=-1>
 271     <center><P ALIGN="CENTER">
 272     Pmw 1.2 -
 273      5 Aug 2003
 274      - <a href="index.html">Home</a>
 275     <br>Manual page last reviewed: 18 May 2002
 276     </p></center>
 277     </font>
 278
 279     </body>
 280     </html>
 281