Pmw/Pmw_1_2/doc/demosandtests.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 demonstrations and tests</title>
   7     </head>
   8
   9     <body bgcolor="#ffffff" text="#000000" link="#0000ee"
  10         vlink="551a8b" alink="ff0000">
  11
  12     <h1 ALIGN="CENTER">Pmw demonstrations and tests</h1>
  13
  14 <center><P ALIGN="CENTER">
  15 <IMG SRC = blue_line.gif ALT = "" WIDTH=320 HEIGHT=5>
  16 </p></center>
  17
  18 <p>
  19   Pmw comes with an extensive range of demonstrations and tests.  The
  20   demonstrations can be used to get a feel for what is provided by Pmw
  21   and the demonstration code can be viewed to see examples of how to
  22   use Pmw.  The tests can be executed to check that there are no
  23   problems with running Pmw in your environment.
  24
  25 </p>
  26
  27 <dl>
  28 <dt> <h2>Demonstrations</h2></dt><dd>
  29 <p>
  30   The Pmw <code>demos</code> directory contains demonstration scripts
  31   showing many of the features of Pmw megawidgets.  To view a
  32   comprehensive package of all the demonstrations, including a view of
  33   the source code, run the <code>All.py</code> script.  Run
  34   <code>All.py -help</code> for a short description of the script's
  35   options.
  36
  37 <p>
  38   All of the demonstrations may also be run separately.  Most of the
  39   demonstrations show some of the features of one of the Pmw
  40   megawidgets.  For example, to see a demonstration of the ButtonBox
  41   megawidget, change into the <code>demos</code> directory and
  42   run
  43
  44 </p>
  45 <dl>
  46 <dd>
  47 <pre>
  48 python ButtonBox.py
  49 </pre>
  50 </dd>
  51 </dl>
  52
  53 <p>
  54   Other demonstrations, which show other features of Pmw include
  55 </p>
  56 <dl>
  57 <dd>
  58 <pre>
  59 BltGraph.py         demonstrates the Pmw interface to
  60                     the BLT graph and vector commands
  61 BltTabset.py        demonstrates the Pmw interface to
  62                     the BLT tabset command
  63 Colors.py           how to set color schemes
  64 ConfigClass.py      how to configure the python class
  65                     of a megawidger component
  66 ErrorHandling.py    how Pmw displays run time errors
  67                     in a window
  68 ExampleDemo.py      template for new demonstrations
  69 Grid.py             the Tkinter Grid geometry manager
  70 LogicalFont.py      how to use standard values for fonts
  71 MessageInfo.py      how to extend the Pmw MegaToplevel
  72                     class
  73 NestedDialogs.py    how nested modal dialogs behave
  74 Resources.py        how to use the option database to
  75                     modify Tk widget option defaults
  76 Resources_Pmw.py    how to use the option database to
  77                     modify megawidget option defaults
  78 ShowBusy.py         demonstrates the Pmw interface to
  79                     the BLT busy command
  80 SpecialEntry.py     deriving from Pmw.EntryField
  81 Spectrum.py         some of the Pmw color handling
  82                     functions
  83 SpeedTest.py        tests the speed of creating Pmw
  84                     megawidgets
  85 TextDisplay.py      how to extend the Pmw MegaWidget
  86                     class
  87 WidgetDestroy.py    megawidget destruction
  88 </pre>
  89 </dd>
  90 </dl>
  91
  92 <b>Creating demonstrations of new megawidgets</b>
  93 <br>
  94 <p>
  95 If you create a new megawidget you can create a demonstration for it
  96 by using the file
  97 <a href="ExampleDemo.py"><code>ExampleDemo.py</code></a> as a
  98 template.  This template allows the demonstration to be run
  99 individually or to be automatically included as part of the
 100 demonstration package <code>All.py</code>.  You should take a copy of
 101 the template and name the new file after your megawidget.  You should
 102 then replace each instance of the word <code>EXAMPLE</code> with the
 103 name of your megawidget and replace the code in the
 104 <code>__init__</code> method with code to create and initialise one or
 105 more instances of your megawidget, which should be a child of
 106 <code>parent</code>.  You can add other methods as necessary.
 107
 108 </p>
 109
 110 </dd>
 111 <dt> <h2>Tests</h2></dt><dd>
 112 <p>
 113   The Pmw <code>tests</code> directory contains a test framework
 114   and a set of test scripts for Pmw.
 115   The tests cover the standard Tkinter module and most of the Pmw megawidgets.
 116   The tests make a great
 117   demonstration of the flexibility of the megawidgets.  Simply change
 118   into the <code>tests</code> directory and run
 119   <code>python All.py</code>.
 120
 121 <p>
 122   If all tests pass there should be no output printed to standard
 123   output.  If any of the tests fail, please send the test output to
 124   the maintainer at
 125   <a href="mailto:gregm@iname.com"><i>gregm@iname.com</i></a>.
 126
 127 </p>
 128
 129 <p>
 130   All of the tests may be run separately.  Most of the tests test the
 131   features of one of the Pmw megawidgets.  For example, to execute the
 132   test for the ButtonBox megawidget, run
 133
 134 </p>
 135
 136 <dl>
 137 <dd>
 138 <pre>
 139 python ButtonBox_test.py
 140 </pre>
 141 </dd>
 142 </dl>
 143
 144 <p>
 145   The Test.py file contains general testing functions and is imported
 146   by all test files.
 147   Other files, which test other features of Pmw include
 148 </p>
 149 <dl>
 150 <dd>
 151 <pre>
 152 Blt_test.py           BLT vector and graph interface
 153 Colors_test.py        setting color schemes
 154 MegaWidget_test.py    creation of megawidget classes
 155 Options_test.py       option and component handling
 156 PmwBase_test.py       more option and component handling
 157 Tkinter_test.py       Tk widgets in the Tkinter module
 158 </pre>
 159 </dd>
 160 </dl>
 161
 162 <b>Creating tests for new megawidgets</b>
 163 <br>
 164 <p>
 165 If you create a new megawidget you should create a test for it.  There
 166 is no template file for creating tests, but by looking at the other
 167 Pmw tests (for example,
 168 <a href="ScrolledText_test.py"><code>ScrolledText_test.py</code></a>) you
 169 will get some idea of how to create a test for your megawidget.
 170
 171 </p>
 172
 173 <p>
 174 The test files are designed to be run both individually or
 175 automatically by the test package <code>All.py</code>.  Each test file
 176 must define the <code>testData</code> tuple.  This consists of a
 177 sequence of 2-element tuples, each tuple being a test specification
 178 for one megawidget.  Usually a file tests only one megawidget and so
 179 there is only one test specification.  The first element in the
 180 specification is the megawidget class and the second is a sequence of
 181 (yet more) 2-element tuples.  In each of these tuples, the first
 182 element is a sequence of individual tests to perform on an instance of
 183 the megawidget and the second element is a dictionary to use for
 184 the keyword arguments when creating the instance.  Each individual
 185 test is a tuple, the meaning of which depends on the type of the first
 186 element, which may be either a string, a function or a method of the
 187 megawidget class, as explained below.
 188
 189 </p>
 190
 191 <ul>
 192 <li>
 193 <p>
 194 If the first element is a string, then it is treated as an option of
 195 the megawidget and configure() is called to set the option to the
 196 value specified by the second element.  After setting the option,
 197 cget() is called to query the option.  If the test tuple has three
 198 elements, then the value returned by cget() must equal the value
 199 specified by the third element.  Otherwise, the value returned must
 200 equal the value specified by the second element. For example,
 201
 202 </p>
 203 <dl>
 204 <dd>
 205 <pre>
 206 ('vscrollmode', 'static'),
 207 ('text_relief', 'sunken'),
 208 ('vscrollmode', 'bogus', 'ValueError: bad vscrollmode ' +
 209   'option "bogus": should be static, dynamic, or none'),
 210 </pre>
 211 </dd>
 212 </dl>
 213
 214 </li>
 215 <li>
 216 <p>
 217 If the first element is a function or method, then the function or
 218 method is called.  The arguments to the call are given by the second
 219 element.  (As a special case, if the second element is not a tuple, it
 220 is used as the only argument to the call.) The test tuple may have 2,
 221 3 or 4 elements.
 222
 223 </p>
 224 <ul>
 225 <li>
 226 <p>
 227 If it has two elements, then the value returned by the call must be
 228 None.  For example,
 229
 230 </p>
 231 <dl>
 232 <dd>
 233 <pre>
 234 (c.exportfile, '/tmp/ScrolledText_test.py'),
 235 (os.unlink, '/tmp/ScrolledText_test.py'),
 236 </pre>
 237 </dd>
 238 </dl>
 239
 240 </li>
 241 <li>
 242 <p>
 243 If it has four elements, then the third element is a dictionary to use
 244 for the keyword arguments in the call and the value returned by the
 245 call must equal the value specified by the fourth element.  For
 246 example,
 247
 248 </p>
 249 <dl>
 250 <dd>
 251 <pre>
 252 (c.search, ('abc', '0.0'), {'nocase': 1}, '2.24'),
 253 </pre>
 254 </dd>
 255 </dl>
 256
 257 </li>
 258 <li>
 259 <p>
 260 If is has three elements and the third element is a dictionary, then
 261 it is used for the keyword arguments in the call and the value
 262 returned by the call must be None.  For example
 263
 264 </p>
 265 <dl>
 266 <dd>
 267 <pre>
 268 (c.configurepane, 'first', {'size' : 200}),
 269 </pre>
 270 </dd>
 271 </dl>
 272
 273 </li>
 274 <li>
 275 <p>
 276 If is has three elements and the third element is not a dictionary,
 277 then the value returned by the call must equal the value specified by
 278 the third element.  For example,
 279
 280 </p>
 281 <dl>
 282 <dd>
 283 <pre>
 284 (c.components, (), ['hull', 'label']),
 285 (c.add, ('Legumes',),
 286   'ValueError: name "Legumes" already exists'),
 287 </pre>
 288 </dd>
 289 </dl>
 290
 291 </li>
 292 </ul>
 293 </li>
 294 </ul>
 295
 296 <p>
 297 Some special functions and values supplied by the Test module that may
 298 be used in the tests include:
 299 </p>
 300 <dl>
 301 <dd>
 302 <pre>
 303 Test.callback       callback taking no arguments
 304 Test.callback1      callback taking one argument
 305 Test.callbackN      callback taking any number of arguments
 306
 307 Test.currentWidget  returns the widget instance being tested
 308 Test.num_options    returns number of options for the widget
 309
 310 Test.earthris       a sample Tkinter.PhotoImage
 311 Test.flagup         a sample Tkinter.BitmapImage
 312 Test.floatvar       a Tkinter.DoubleVar
 313 Test.stringvar      a Tkinter.StringVar
 314 </pre>
 315 </dd>
 316 </dl>
 317
 318 <p>
 319   To slow down a test (to see what is being displayed), add the
 320   following line which sets the delay between tests to (say) 1000
 321   milliseconds:
 322
 323 </p>
 324 <dl>
 325 <dd>
 326 <pre>
 327 Test.setdelay(1000)
 328 </pre>
 329 </dd>
 330 </dl>
 331
 332 <p>
 333   To print information about what is being tested, add the line:
 334
 335 </p>
 336 <dl>
 337 <dd>
 338 <pre>
 339 Test.setverbose(1)
 340 </pre>
 341 </dd>
 342 </dl>
 343
 344 </dd>
 345 </dl>
 346
 347
 348     <center><P ALIGN="CENTER">
 349     <IMG SRC = blue_line.gif ALT = "" WIDTH=320 HEIGHT=5>
 350     </p></center>
 351
 352
 353     <font size=-1>
 354     <center><P ALIGN="CENTER">
 355     Pmw 1.2 -
 356      5 Aug 2003
 357      - <a href="index.html">Home</a>
 358
 359     </p></center>
 360     </font>
 361
 362     </body>
 363     </html>
 364