wxPython/docs/wxPythonManual.html

   1 <?xml version="1.0" encoding="iso-8859-1" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   4 <head>
   5 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
   6 <meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
   7 <title>The wxPython Manual</title>
   8 <meta name="author" content="Patrick K. O'Brien" />
   9 <meta name="organization" content="Orbtech" />
  10 <meta name="date" content="2004-03-26" />
  11 <style type="text/css">
  12
  13 /*
  14 :Author: David Goodger
  15 :Contact: goodger@users.sourceforge.net
  16 :Date: $Date$
  17 :Revision: $Revision$
  18 :Copyright: This stylesheet has been placed in the public domain.
  19
  20 Default cascading style sheet for the HTML output of Docutils.
  21
  22 See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
  23 customize this style sheet.
  24 */
  25
  26 /* used to remove borders from tables and images */
  27 .borderless, table.borderless td, table.borderless th {
  28   border: 0 }
  29
  30 table.borderless td, table.borderless th {
  31   /* Override padding for "table.docutils td" with "! important".
  32      The right padding separates the table cells. */
  33   padding: 0 0.5em 0 0 ! important }
  34
  35 .first {
  36   /* Override more specific margin styles with "! important". */
  37   margin-top: 0 ! important }
  38
  39 .last, .with-subtitle {
  40   margin-bottom: 0 ! important }
  41
  42 .hidden {
  43   display: none }
  44
  45 a.toc-backref {
  46   text-decoration: none ;
  47   color: black }
  48
  49 blockquote.epigraph {
  50   margin: 2em 5em ; }
  51
  52 dl.docutils dd {
  53   margin-bottom: 0.5em }
  54
  55 /* Uncomment (and remove this text!) to get bold-faced definition list terms
  56 dl.docutils dt {
  57   font-weight: bold }
  58 */
  59
  60 div.abstract {
  61   margin: 2em 5em }
  62
  63 div.abstract p.topic-title {
  64   font-weight: bold ;
  65   text-align: center }
  66
  67 div.admonition, div.attention, div.caution, div.danger, div.error,
  68 div.hint, div.important, div.note, div.tip, div.warning {
  69   margin: 2em ;
  70   border: medium outset ;
  71   padding: 1em }
  72
  73 div.admonition p.admonition-title, div.hint p.admonition-title,
  74 div.important p.admonition-title, div.note p.admonition-title,
  75 div.tip p.admonition-title {
  76   font-weight: bold ;
  77   font-family: sans-serif }
  78
  79 div.attention p.admonition-title, div.caution p.admonition-title,
  80 div.danger p.admonition-title, div.error p.admonition-title,
  81 div.warning p.admonition-title {
  82   color: red ;
  83   font-weight: bold ;
  84   font-family: sans-serif }
  85
  86 /* Uncomment (and remove this text!) to get reduced vertical space in
  87    compound paragraphs.
  88 div.compound .compound-first, div.compound .compound-middle {
  89   margin-bottom: 0.5em }
  90
  91 div.compound .compound-last, div.compound .compound-middle {
  92   margin-top: 0.5em }
  93 */
  94
  95 div.dedication {
  96   margin: 2em 5em ;
  97   text-align: center ;
  98   font-style: italic }
  99
 100 div.dedication p.topic-title {
 101   font-weight: bold ;
 102   font-style: normal }
 103
 104 div.figure {
 105   margin-left: 2em ;
 106   margin-right: 2em }
 107
 108 div.footer, div.header {
 109   clear: both;
 110   font-size: smaller }
 111
 112 div.line-block {
 113   display: block ;
 114   margin-top: 1em ;
 115   margin-bottom: 1em }
 116
 117 div.line-block div.line-block {
 118   margin-top: 0 ;
 119   margin-bottom: 0 ;
 120   margin-left: 1.5em }
 121
 122 div.sidebar {
 123   margin-left: 1em ;
 124   border: medium outset ;
 125   padding: 1em ;
 126   background-color: #ffffee ;
 127   width: 40% ;
 128   float: right ;
 129   clear: right }
 130
 131 div.sidebar p.rubric {
 132   font-family: sans-serif ;
 133   font-size: medium }
 134
 135 div.system-messages {
 136   margin: 5em }
 137
 138 div.system-messages h1 {
 139   color: red }
 140
 141 div.system-message {
 142   border: medium outset ;
 143   padding: 1em }
 144
 145 div.system-message p.system-message-title {
 146   color: red ;
 147   font-weight: bold }
 148
 149 div.topic {
 150   margin: 2em }
 151
 152 h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
 153 h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
 154   margin-top: 0.4em }
 155
 156 h1.title {
 157   text-align: center }
 158
 159 h2.subtitle {
 160   text-align: center }
 161
 162 hr.docutils {
 163   width: 75% }
 164
 165 img.align-left {
 166   clear: left }
 167
 168 img.align-right {
 169   clear: right }
 170
 171 ol.simple, ul.simple {
 172   margin-bottom: 1em }
 173
 174 ol.arabic {
 175   list-style: decimal }
 176
 177 ol.loweralpha {
 178   list-style: lower-alpha }
 179
 180 ol.upperalpha {
 181   list-style: upper-alpha }
 182
 183 ol.lowerroman {
 184   list-style: lower-roman }
 185
 186 ol.upperroman {
 187   list-style: upper-roman }
 188
 189 p.attribution {
 190   text-align: right ;
 191   margin-left: 50% }
 192
 193 p.caption {
 194   font-style: italic }
 195
 196 p.credits {
 197   font-style: italic ;
 198   font-size: smaller }
 199
 200 p.label {
 201   white-space: nowrap }
 202
 203 p.rubric {
 204   font-weight: bold ;
 205   font-size: larger ;
 206   color: maroon ;
 207   text-align: center }
 208
 209 p.sidebar-title {
 210   font-family: sans-serif ;
 211   font-weight: bold ;
 212   font-size: larger }
 213
 214 p.sidebar-subtitle {
 215   font-family: sans-serif ;
 216   font-weight: bold }
 217
 218 p.topic-title {
 219   font-weight: bold }
 220
 221 pre.address {
 222   margin-bottom: 0 ;
 223   margin-top: 0 ;
 224   font-family: serif ;
 225   font-size: 100% }
 226
 227 pre.literal-block, pre.doctest-block {
 228   margin-left: 2em ;
 229   margin-right: 2em ;
 230   background-color: #eeeeee }
 231
 232 span.classifier {
 233   font-family: sans-serif ;
 234   font-style: oblique }
 235
 236 span.classifier-delimiter {
 237   font-family: sans-serif ;
 238   font-weight: bold }
 239
 240 span.interpreted {
 241   font-family: sans-serif }
 242
 243 span.option {
 244   white-space: nowrap }
 245
 246 span.pre {
 247   white-space: pre }
 248
 249 span.problematic {
 250   color: red }
 251
 252 span.section-subtitle {
 253   /* font-size relative to parent (h1..h6 element) */
 254   font-size: 80% }
 255
 256 table.citation {
 257   border-left: solid 1px gray;
 258   margin-left: 1px }
 259
 260 table.docinfo {
 261   margin: 2em 4em }
 262
 263 table.docutils {
 264   margin-top: 0.5em ;
 265   margin-bottom: 0.5em }
 266
 267 table.footnote {
 268   border-left: solid 1px black;
 269   margin-left: 1px }
 270
 271 table.docutils td, table.docutils th,
 272 table.docinfo td, table.docinfo th {
 273   padding-left: 0.5em ;
 274   padding-right: 0.5em ;
 275   vertical-align: top }
 276
 277 table.docutils th.field-name, table.docinfo th.docinfo-name {
 278   font-weight: bold ;
 279   text-align: left ;
 280   white-space: nowrap ;
 281   padding-left: 0 }
 282
 283 h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
 284 h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
 285   font-size: 100% }
 286
 287 tt.docutils {
 288   background-color: #eeeeee }
 289
 290 ul.auto-toc {
 291   list-style-type: none }
 292
 293 </style>
 294 </head>
 295 <body>
 296 <div class="document" id="the-wxpython-manual">
 297 <h1 class="title">The wxPython Manual</h1>
 298 <h2 class="subtitle" id="a-guide-to-wxpython-for-python-programmers">A guide to wxPython for Python programmers</h2>
 299 <table class="docinfo" frame="void" rules="none">
 300 <col class="docinfo-name" />
 301 <col class="docinfo-content" />
 302 <tbody valign="top">
 303 <tr><th class="docinfo-name">Author:</th>
 304 <td>Patrick K. O'Brien</td></tr>
 305 <tr><th class="docinfo-name">Contact:</th>
 306 <td><a class="first last reference" href="mailto:pobrien&#64;orbtech.com">pobrien&#64;orbtech.com</a></td></tr>
 307 <tr><th class="docinfo-name">Organization:</th>
 308 <td><a class="first last reference" href="http://www.orbtech.com/">Orbtech</a></td></tr>
 309 <tr><th class="docinfo-name">Date:</th>
 310 <td>2004-03-26</td></tr>
 311 <tr><th class="docinfo-name">Revision:</th>
 312 <td>1.3</td></tr>
 313 <tr class="field"><th class="docinfo-name">License:</th><td class="field-body">wxWindows Free Documentation Licence, Version 3</td>
 314 </tr>
 315 </tbody>
 316 </table>
 317 <div class="contents topic">
 318 <p class="topic-title first"><a id="contents" name="contents">Contents</a></p>
 319 <ul class="simple">
 320 <li><a class="reference" href="#introduction" id="id1" name="id1">Introduction</a></li>
 321 <li><a class="reference" href="#what-is-wxpython" id="id2" name="id2">What is wxPython?</a></li>
 322 <li><a class="reference" href="#wxpython-requirements" id="id3" name="id3">wxPython requirements</a><ul>
 323 <li><a class="reference" href="#ms-windows" id="id4" name="id4">MS-Windows</a></li>
 324 <li><a class="reference" href="#linux-or-unix" id="id5" name="id5">Linux or Unix</a></li>
 325 <li><a class="reference" href="#mac-os-x" id="id6" name="id6">Mac OS X</a></li>
 326 </ul>
 327 </li>
 328 <li><a class="reference" href="#what-is-wxwidgets" id="id7" name="id7">What is wxWidgets?</a></li>
 329 <li><a class="reference" href="#why-another-cross-platform-development-tool" id="id8" name="id8">Why another cross-platform development tool?</a></li>
 330 <li><a class="reference" href="#wxpython-overview" id="id9" name="id9">wxPython Overview</a></li>
 331 <li><a class="reference" href="#utilities-and-libraries-supplied-with-wxpython" id="id10" name="id10">Utilities and libraries supplied with wxPython</a></li>
 332 <li><a class="reference" href="#creating-and-deleting-wxpython-objects" id="id11" name="id11">Creating and deleting wxPython objects</a></li>
 333 <li><a class="reference" href="#app-overview" id="id12" name="id12">App overview</a><ul>
 334 <li><a class="reference" href="#application-initialization" id="id13" name="id13">Application initialization</a></li>
 335 <li><a class="reference" href="#application-shutdown" id="id14" name="id14">Application shutdown</a></li>
 336 </ul>
 337 </li>
 338 <li><a class="reference" href="#sizer-overview" id="id15" name="id15">Sizer overview</a><ul>
 339 <li><a class="reference" href="#the-idea-behind-sizers" id="id16" name="id16">The idea behind sizers</a></li>
 340 <li><a class="reference" href="#common-features" id="id17" name="id17">Common features</a><ul>
 341 <li><a class="reference" href="#a-minimal-size" id="id18" name="id18">A minimal size</a></li>
 342 <li><a class="reference" href="#a-border" id="id19" name="id19">A border</a></li>
 343 <li><a class="reference" href="#an-alignment" id="id20" name="id20">An alignment</a></li>
 344 <li><a class="reference" href="#a-stretch-factor" id="id21" name="id21">A stretch factor</a></li>
 345 </ul>
 346 </li>
 347 <li><a class="reference" href="#boxsizer" id="id22" name="id22">BoxSizer</a></li>
 348 <li><a class="reference" href="#staticboxsizer" id="id23" name="id23">StaticBoxSizer</a></li>
 349 <li><a class="reference" href="#gridsizer" id="id24" name="id24">GridSizer</a></li>
 350 <li><a class="reference" href="#flexgridsizer" id="id25" name="id25">FlexGridSizer</a></li>
 351 <li><a class="reference" href="#notebooksizer" id="id26" name="id26">NotebookSizer</a></li>
 352 <li><a class="reference" href="#programming-with-boxsizer" id="id27" name="id27">Programming with BoxSizer</a></li>
 353 <li><a class="reference" href="#programming-with-gridsizer" id="id28" name="id28">Programming with GridSizer</a></li>
 354 <li><a class="reference" href="#programming-with-flexgridsizer" id="id29" name="id29">Programming with FlexGridSizer</a></li>
 355 <li><a class="reference" href="#programming-with-notebooksizer" id="id30" name="id30">Programming with NotebookSizer</a></li>
 356 <li><a class="reference" href="#programming-with-staticboxsizer" id="id31" name="id31">Programming with StaticBoxSizer</a></li>
 357 <li><a class="reference" href="#dialog-createbuttonsizer" id="id32" name="id32">Dialog.CreateButtonSizer</a></li>
 358 </ul>
 359 </li>
 360 <li><a class="reference" href="#date-and-time-classes-overview" id="id33" name="id33">Date and time classes overview</a><ul>
 361 <li><a class="reference" href="#all-date-time-classes-at-a-glance" id="id34" name="id34">All date/time classes at a glance</a></li>
 362 <li><a class="reference" href="#datetime-characteristics" id="id35" name="id35">DateTime characteristics</a></li>
 363 <li><a class="reference" href="#difference-between-datespan-and-timespan" id="id36" name="id36">Difference between DateSpan and TimeSpan</a></li>
 364 <li><a class="reference" href="#date-arithmetics" id="id37" name="id37">Date arithmetics</a></li>
 365 <li><a class="reference" href="#time-zone-considerations" id="id38" name="id38">Time zone considerations</a></li>
 366 <li><a class="reference" href="#daylight-saving-time-dst" id="id39" name="id39">Daylight saving time (DST)</a></li>
 367 <li><a class="reference" href="#datetime-and-holidays" id="id40" name="id40">DateTime and Holidays</a></li>
 368 </ul>
 369 </li>
 370 <li><a class="reference" href="#classes-by-category" id="id41" name="id41">Classes by category</a></li>
 371 <li><a class="reference" href="#id-constants" id="id42" name="id42">ID constants</a></li>
 372 <li><a class="reference" href="#source-document" id="id43" name="id43">Source document</a></li>
 373 <li><a class="reference" href="#submitting-changes-to-the-source-document" id="id44" name="id44">Submitting changes to the source document</a></li>
 374 <li><a class="reference" href="#contributors" id="id45" name="id45">Contributors</a></li>
 375 <li><a class="reference" href="#license" id="id46" name="id46">License</a></li>
 376 </ul>
 377 </div>
 378 <div class="section">
 379 <h1><a class="toc-backref" href="#id1" id="introduction" name="introduction">Introduction</a></h1>
 380 <p>This is a guide to the wxPython GUI toolkit, written <strong>by</strong> a Python
 381 programmer <strong>for</strong> his fellow Python programmers.  It began as a
 382 simple translation of the wxWidgets documentation (which is written
 383 for C++ programmers), and evolved from there.  And while there's
 384 nothing wrong with C++...</p>
 385 <p>Okay, you got me there.  I hate C++.  That's why I use Python.  If you
 386 like C++, go read the wxWidgets documentation.  If you'd rather read a
 387 guide that's written with Python programmers in mind, keep reading
 388 this one.  If you like it, feel free to send me freshly roasted coffee
 389 beans, dark chocolate, and large denomination currency.  Better yet,
 390 buy huge quantities of my wxPython book (written with Robin Dunn) and
 391 send one to each of your friends, relatives, and coworkers.</p>
 392 </div>
 393 <div class="section">
 394 <h1><a class="toc-backref" href="#id2" id="what-is-wxpython" name="what-is-wxpython">What is wxPython?</a></h1>
 395 <p>wxPython is a GUI toolkit for the Python programming language.  It
 396 allows Python programmers to create programs with a robust, highly
 397 functional graphical user interface, simply and easily.  It is
 398 implemented as a Python extension module (native code) that wraps the
 399 popular wxWidgets cross platform GUI library, which is written in C++.</p>
 400 <p>Like Python and wxWidgets, wxPython is Open Source, which means that
 401 it is free for anyone to use and the source code is available for
 402 anyone to look at and modify.  And anyone can contribute fixes or
 403 enhnacments to the project.</p>
 404 <p>wxPython is a cross-platform toolkit.  This means that the same
 405 program will run on multiple platforms without modification.
 406 Currently supported platforms are 32-bit Microsoft Windows, most Unix
 407 or unix-like systems, and Macintosh OS X.</p>
 408 <p>Since the language is Python, wxPython programs are simple, easy to
 409 write and easy to understand.</p>
 410 </div>
 411 <div class="section">
 412 <h1><a class="toc-backref" href="#id3" id="wxpython-requirements" name="wxpython-requirements">wxPython requirements</a></h1>
 413 <p>To make use of wxPython, you currently need one of the following
 414 setups.</p>
 415 <div class="section">
 416 <h2><a class="toc-backref" href="#id4" id="ms-windows" name="ms-windows">MS-Windows</a></h2>
 417 <ul class="simple">
 418 <li>A 486 or higher PC running MS Windows.</li>
 419 <li>At least ?? MB of disk space.</li>
 420 </ul>
 421 </div>
 422 <div class="section">
 423 <h2><a class="toc-backref" href="#id5" id="linux-or-unix" name="linux-or-unix">Linux or Unix</a></h2>
 424 <ul class="simple">
 425 <li>Almost any C++ compiler, including GNU C++ (EGCS 1.1.1 or above).</li>
 426 <li>Almost any Unix workstation, and one of: GTK+ 1.2, GTK+ 2.0, Motif
 427 1.2 or higher, Lesstif.</li>
 428 <li>At least ?? MB of disk space.</li>
 429 </ul>
 430 </div>
 431 <div class="section">
 432 <h2><a class="toc-backref" href="#id6" id="mac-os-x" name="mac-os-x">Mac OS X</a></h2>
 433 <ul class="simple">
 434 <li>A PowerPC Mac running Mac OS X 10.x.</li>
 435 <li>At least ?? MB of disk space.</li>
 436 </ul>
 437 </div>
 438 </div>
 439 <div class="section">
 440 <h1><a class="toc-backref" href="#id7" id="what-is-wxwidgets" name="what-is-wxwidgets">What is wxWidgets?</a></h1>
 441 <p>wxWidgets is a C++ framework providing GUI (Graphical User Interface)
 442 and other facilities on more than one platform.  Version 2 currently
 443 supports all desktop versions of MS Windows, Unix with GTK+, Unix with
 444 Motif, and MacOS.  An OS/2 port is in progress.</p>
 445 <p>wxWidgets was originally developed at the Artificial Intelligence
 446 Applications Institute, University of Edinburgh, for internal use, and
 447 was first made publicly available in 1992.  Version 2 is a vastly
 448 improved version written and maintained by Julian Smart, Robert
 449 Roebling, Vadim Zeitlin, Vaclav Slavik and many others.</p>
 450 <p>Please note that in the following, &quot;MS Windows&quot; often refers to all
 451 platforms related to Microsoft Windows, including 16-bit and 32-bit
 452 variants, unless otherwise stated.  All trademarks are acknowledged.</p>
 453 </div>
 454 <div class="section">
 455 <h1><a class="toc-backref" href="#id8" id="why-another-cross-platform-development-tool" name="why-another-cross-platform-development-tool">Why another cross-platform development tool?</a></h1>
 456 <p>wxWidgets was developed to provide a cheap and flexible way to
 457 maximize investment in GUI application development.  While a number of
 458 commercial class libraries already existed for cross-platform
 459 development, none met all of the following criteria:</p>
 460 <ul class="simple">
 461 <li>low price</li>
 462 <li>source availability</li>
 463 <li>simplicity of programming</li>
 464 <li>support for a wide range of compilers</li>
 465 </ul>
 466 <p>Since wxWidgets was started, several other free or almost-free GUI
 467 frameworks have emerged.  However, none has the range of features,
 468 flexibility, documentation and the well-established development team
 469 that wxWidgets has.</p>
 470 <p>As open source software, wxWidgets has benefited from comments, ideas,
 471 bug fixes, enhancements and the sheer enthusiasm of users.  This gives
 472 wxWidgets a certain advantage over its commercial competitors (and
 473 over free libraries without an independent development team), plus a
 474 robustness against the transience of one individual or company.  This
 475 openness and availability of source code is especially important when
 476 the future of thousands of lines of application code may depend upon
 477 the longevity of the underlying class library.</p>
 478 <p>Version 2 goes much further than previous versions in terms of
 479 generality and features, allowing applications to be produced that are
 480 often indistinguishable from those produced using single-platform
 481 toolkits such as Motif, GTK+ and MFC.</p>
 482 <p>The importance of using a platform-independent class library cannot be
 483 overstated, since GUI application development is very time-consuming,
 484 and sustained popularity of particular GUIs cannot be guaranteed.
 485 Code can very quickly become obsolete if it addresses the wrong
 486 platform or audience.  wxWidgets helps to insulate the programmer from
 487 these winds of change.  Although wxWidgets may not be suitable for
 488 every application (such as an OLE-intensive program), it provides
 489 access to most of the functionality a GUI program normally requires,
 490 plus many extras such as network programming, PostScript output, and
 491 HTML rendering; and it can of course be extended as needs dictate.  As
 492 a bonus, it provides a far cleaner and easier programming interface
 493 than the native APIs.  Programmers may find it worthwhile to use
 494 wxWidgets even if they are developing on only one platform.</p>
 495 <p>It is impossible to sum up the functionality of wxWidgets in a few
 496 paragraphs, but here are some of the benefits:</p>
 497 <ul class="simple">
 498 <li>Low cost (free, in fact!)</li>
 499 <li>You get the source.</li>
 500 <li>Available on a variety of popular platforms.</li>
 501 <li>Works with almost all popular C++ compilers and Python.</li>
 502 <li>Over 50 example programs.</li>
 503 <li>Over 1000 pages of printable and on-line documentation.</li>
 504 <li>Includes Tex2RTF, to allow you to produce your own documentation in
 505 Windows Help, HTML and Word RTF formats.</li>
 506 <li>Simple-to-use, object-oriented API.</li>
 507 <li>Flexible event system.</li>
 508 <li>Graphics calls include lines, rounded rectangles, splines,
 509 polylines, etc.</li>
 510 <li>Constraint-based and sizer-based layouts.</li>
 511 <li>Print/preview and document/view architectures.</li>
 512 <li>Toolbar, notebook, tree control, advanced list control classes.</li>
 513 <li>PostScript generation under Unix, normal MS Windows printing on the
 514 PC.</li>
 515 <li>MDI (Multiple Document Interface) support.</li>
 516 <li>Can be used to create DLLs under Windows, dynamic libraries on Unix.</li>
 517 <li>Common dialogs for file browsing, printing, colour selection, etc.</li>
 518 <li>Under MS Windows, support for creating metafiles and copying them to
 519 the clipboard.</li>
 520 <li>An API for invoking help from applications.</li>
 521 <li>Ready-to-use HTML window (supporting a subset of HTML).</li>
 522 <li>Dialog Editor for building dialogs.</li>
 523 <li>Network support via a family of socket and protocol classes.</li>
 524 <li>Support for platform independent image processing.</li>
 525 <li>Built-in support for many file formats (BMP, PNG, JPEG, GIF, XPM,
 526 PNM, PCX).</li>
 527 </ul>
 528 </div>
 529 <div class="section">
 530 <h1><a class="toc-backref" href="#id9" id="wxpython-overview" name="wxpython-overview">wxPython Overview</a></h1>
 531 <p>To set a wxPython application going, you will need to derive an App
 532 class and override App.OnInit.</p>
 533 <p>An application must have a top-level Frame or Dialog window.  Each
 534 frame may contain one or more instances of classes such as Panel,
 535 SplitterWindow or other windows and controls.</p>
 536 <p>A frame can have a MenuBar, a ToolBar, a status line, and an Icon for
 537 when the frame is iconized.</p>
 538 <p>A Panel is used to place controls (classes derived from Control) which
 539 are used for user interaction.  Examples of controls are Button,
 540 CheckBox, Choice, ListBox, RadioBox, Slider.</p>
 541 <p>Instances of Dialog can also be used for controls, and they have the
 542 advantage of not requiring a separate frame.</p>
 543 <p>Instead of creating a dialog box and populating it with items, it is
 544 possible to choose one of the convenient common dialog classes, such
 545 as MessageDialog and FileDialog.</p>
 546 <p>You never draw directly onto a window.  Instead, you use a device
 547 context (DC).  DC is the base for ClientDC, PaintDC, MemoryDC,
 548 PostScriptDC, MemoryDC, MetafileDC and PrinterDC.  If your drawing
 549 functions have DC as a parameter, you can pass any of these DCs to the
 550 function, and thus use the same code to draw to several different
 551 devices.  You can draw using the member functions of DC, such as
 552 DC.DrawLine and DC.DrawText.  Control colour on a window (Colour) with
 553 brushes (Brush) and pens (Pen).</p>
 554 <!-- To intercept events, you add a DECLARE_EVENT_TABLE macro to the
 555 window class declaration, and put a BEGIN_EVENT_TABLE
 556 ... END_EVENT_TABLE block in the implementation file. Between these
 557 macros, you add event macros which map the event (such as a mouse
 558 click) to a member function. These might override predefined event
 559 handlers such as for KeyEvent and MouseEvent. -->
 560 <p>Most modern applications will have an on-line, hypertext help system;
 561 for this, you need Help and the HelpController class to control
 562 Help.</p>
 563 <p>GUI applications aren't all graphical wizardry.  You'll also need
 564 lists and hash tables.  But since you're working with Python, you
 565 should use the ones Python provides (list, tuple, dict), rather than
 566 the wxWidgets versions.  Same goes for the database related classes.
 567 The basic rule of thumb is this: If you can do it directly in Python,
 568 you probably should.  If there is a reason not to use a Python data
 569 type, wxPython will provide a wrapper for the wxWidgets class.</p>
 570 <p>You will undoubtedly need some platform-independent file functions,
 571 and you may find it handy to maintain and search a list of paths using
 572 PathList. There's a miscellany of operating system and other
 573 functions.</p>
 574 <p>See also Classes by Category for a list of classes.</p>
 575 </div>
 576 <div class="section">
 577 <h1><a class="toc-backref" href="#id10" id="utilities-and-libraries-supplied-with-wxpython" name="utilities-and-libraries-supplied-with-wxpython">Utilities and libraries supplied with wxPython</a></h1>
 578 <p>In addition to the core wxWidgets library, a number of further
 579 libraries and utilities are supplied with each distribution.</p>
 580 <p>[Need to list these.]</p>
 581 </div>
 582 <div class="section">
 583 <h1><a class="toc-backref" href="#id11" id="creating-and-deleting-wxpython-objects" name="creating-and-deleting-wxpython-objects">Creating and deleting wxPython objects</a></h1>
 584 <p>[This section needs to be reviewed.]</p>
 585 <!-- In general, classes derived from wxWindow must dynamically
 586 allocated with new and deleted with delete. If you delete a window,
 587 all of its children and descendants will be automatically deleted,
 588 so you don't need to delete these descendants explicitly. -->
 589 <!-- When deleting a frame or dialog, use Destroy rather than delete so
 590 that the wxWidgets delayed deletion can take effect. This waits
 591 until idle time (when all messages have been processed) to actually
 592 delete the window, to avoid problems associated with the GUI
 593 sending events to deleted windows. -->
 594 <!-- If you decide to allocate a C++ array of objects (such as wxBitmap)
 595 that may be cleaned up by wxWidgets, make sure you delete the array
 596 explicitly before wxWidgets has a chance to do so on exit, since
 597 calling delete on array members will cause memory problems. -->
 598 <!-- wxColour can be created statically: it is not automatically cleaned
 599 up and is unlikely to be shared between other objects; it is
 600 lightweight enough for copies to be made. -->
 601 <!-- Beware of deleting objects such as a wxPen or wxBitmap if they are
 602 still in use. Windows is particularly sensitive to this: so make
 603 sure you make calls like wxDC::SetPen(wxNullPen) or
 604 wxDC::SelectObject(wxNullBitmap) before deleting a drawing object
 605 that may be in use. Code that doesn't do this will probably work
 606 fine on some platforms, and then fail under Windows. -->
 607 </div>
 608 <div class="section">
 609 <h1><a class="toc-backref" href="#id12" id="app-overview" name="app-overview">App overview</a></h1>
 610 <p>Classes: wx.App</p>
 611 <div class="section">
 612 <h2><a class="toc-backref" href="#id13" id="application-initialization" name="application-initialization">Application initialization</a></h2>
 613 <p>The OnInit method defined for a class derived from wx.App will usually
 614 create a top window as a bare minimum.</p>
 615 <p>OnInit must return a boolean value to indicate whether processing
 616 should continue (True) or not (False).  You call App.SetTopWindow to
 617 let wxPython know about the top window.</p>
 618 <p>An application closes by destroying all windows.  Because all frames
 619 must be destroyed for the application to exit, it is advisable to use
 620 parent frames wherever possible when creating new frames, so that
 621 deleting the top level frame will automatically delete child frames.
 622 The alternative is to explicitly delete child frames in the top-level
 623 frame's CloseEvent handler.</p>
 624 <p>In emergencies the wx.Exit() function can be called to kill the
 625 application, however, normally the application shuts down
 626 automatically, see below.</p>
 627 <p>An example of defining an application follows:</p>
 628 <pre class="literal-block">
 629 import wx
 630
 631 from frame import Frame
 632
 633 class App(wx.App):
 634     &quot;&quot;&quot;Application class.&quot;&quot;&quot;
 635
 636     def OnInit(self):
 637         self.frame = Frame()
 638         self.frame.Show()
 639         self.SetTopWindow(self.frame)
 640         return True
 641
 642 def main():
 643     app = App()
 644     app.MainLoop()
 645
 646 if __name__ == '__main__':
 647     main()
 648 </pre>
 649 </div>
 650 <div class="section">
 651 <h2><a class="toc-backref" href="#id14" id="application-shutdown" name="application-shutdown">Application shutdown</a></h2>
 652 <p>The application normally shuts down when the last of its top level
 653 windows is closed.  This is normally the expected behaviour and means
 654 that it is enough to call Close() in response to the &quot;Exit&quot; menu
 655 command if your program has a single top level window.  If this
 656 behaviour is not desirable, App.SetExitOnFrameDelete can be called to
 657 change it.  Note that such logic doesn't apply for the windows shown
 658 before the program enters the main loop: in other words, you can
 659 safely show a dialog from App.OnInit and not be afraid that your
 660 application terminates when this dialog -- which is the last top level
 661 window for the moment -- is closed.</p>
 662 <p>Another aspect of the application shutdown is the OnExit which is
 663 called when the application exits but before wxPython cleans up its
 664 internal structures.  You should delete all wxPython objects that you
 665 created by the time OnExit finishes.</p>
 666 <p>For example, this code may crash:</p>
 667 <p>[Need examples of objects needing cleanup to keep app from crashing.]</p>
 668 </div>
 669 </div>
 670 <div class="section">
 671 <h1><a class="toc-backref" href="#id15" id="sizer-overview" name="sizer-overview">Sizer overview</a></h1>
 672 <p>Classes: wx.Sizer, wx.GridSizer, wx.FlexGridSizer, wx.BoxSizer,
 673 wx.StaticBoxSizer, wx.NotebookSizer, wx.CreateButtonSizer</p>
 674 <table border="1" class="docutils">
 675 <colgroup>
 676 <col width="21%" />
 677 <col width="79%" />
 678 </colgroup>
 679 <tbody valign="top">
 680 <tr><td>Sizer</td>
 681 <td>Abstract base class.</td>
 682 </tr>
 683 <tr><td>GridSizer</td>
 684 <td>A sizer for laying out windows in a grid with all
 685 fields having the same size.</td>
 686 </tr>
 687 <tr><td>FlexGridSizer</td>
 688 <td>A sizer for laying out windows in a flexible grid.</td>
 689 </tr>
 690 <tr><td>BoxSizer</td>
 691 <td>A sizer for laying out windows in a row or column.</td>
 692 </tr>
 693 <tr><td>StaticBoxSizer</td>
 694 <td>Same as BoxSizer, but with a surrounding static box.</td>
 695 </tr>
 696 <tr><td>NotebookSizer</td>
 697 <td>Sizer to use with the Notebook control.</td>
 698 </tr>
 699 </tbody>
 700 </table>
 701 <p>Sizers, as represented by the wx.Sizer class and its descendants in
 702 the wxPython class hierarchy, have become the method of choice to
 703 define the layout of controls in dialogs in wxPython because of their
 704 ability to create visually appealing dialogs independent of the
 705 platform, taking into account the differences in size and style of the
 706 individual controls.  Editors such as wxDesigner, wxrcedit, XRCed and
 707 wxWorkshop create dialogs based exclusively on sizers, practically
 708 forcing the user to create platform independent layouts without
 709 compromises.</p>
 710 <div class="section">
 711 <h2><a class="toc-backref" href="#id16" id="the-idea-behind-sizers" name="the-idea-behind-sizers">The idea behind sizers</a></h2>
 712 <p>The layout algorithm used by sizers in wxPython is closely related to
 713 layout systems in other GUI toolkits, such as Java's AWT, the GTK
 714 toolkit or the Qt toolkit.  It is based upon the idea of individual
 715 subwindows reporting their minimal required size and their ability to
 716 get stretched if the size of the parent window has changed.  This will
 717 most often mean that the programmer does not set the start-up size of
 718 a dialog, the dialog will rather be assigned a sizer and this sizer
 719 will be queried about the recommended size.  This sizer in turn will
 720 query its children (which can be normal windows, empty space or other
 721 sizers) so that a hierarchy of sizers can be constructed.  Note that
 722 wx.Sizer does not derive from wx.Window and thus does not interfere
 723 with tab ordering and requires very few resources compared to a real
 724 window on screen.</p>
 725 <p>What makes sizers so well fitted for use in wxPython is the fact that
 726 every control reports its own minimal size and the algorithm can
 727 handle differences in font sizes or different window (dialog item)
 728 sizes on different platforms without problems.  For example, if the
 729 standard font as well as the overall design of Linux/GTK widgets
 730 requires more space than on Windows, the initial dialog size will
 731 automatically be bigger on Linux/GTK than on Windows.</p>
 732 <p>There are currently five different kinds of sizers available in
 733 wxPython.  Each represents either a certain way to lay out dialog items
 734 in a dialog or it fulfils a special task such as wrapping a static box
 735 around a dialog item (or another sizer).  These sizers will be
 736 discussed one by one in the text below.</p>
 737 </div>
 738 <div class="section">
 739 <h2><a class="toc-backref" href="#id17" id="common-features" name="common-features">Common features</a></h2>
 740 <p>All sizers are containers, that is, they are used to lay out one
 741 dialog item (or several dialog items), which they contain.  Such items
 742 are sometimes referred to as the children of the sizer.  Independent
 743 of how the individual sizers lay out their children, all children have
 744 certain features in common:</p>
 745 <div class="section">
 746 <h3><a class="toc-backref" href="#id18" id="a-minimal-size" name="a-minimal-size">A minimal size</a></h3>
 747 <p>This minimal size is usually identical to the initial size of the
 748 controls and may either be set explicitly in the size field of the
 749 control constructor or may be calculated by wxPython, typically by
 750 setting the height and/or the width of the item to -1.  Note that only
 751 some controls can calculate their size (such as a checkbox) whereas
 752 others (such as a listbox) don't have any natural width or height and
 753 thus require an explicit size.  Some controls can calculate their
 754 height, but not their width (e.g. a single line text control):</p>
 755 <p>[Need graphics]</p>
 756 </div>
 757 <div class="section">
 758 <h3><a class="toc-backref" href="#id19" id="a-border" name="a-border">A border</a></h3>
 759 <p>The border is just empty space and is used to separate dialog items in
 760 a dialog.  This border can either be all around, or at any combination
 761 of sides such as only above and below the control.  The thickness of
 762 this border must be set explicitly, typically 5 points.  The following
 763 samples show dialogs with only one dialog item (a button) and a border
 764 of 0, 5, and 10 pixels around the button:</p>
 765 <p>[Need graphics]</p>
 766 </div>
 767 <div class="section">
 768 <h3><a class="toc-backref" href="#id20" id="an-alignment" name="an-alignment">An alignment</a></h3>
 769 <p>Often, a dialog item is given more space than its minimal size plus
 770 its border.  Depending on what flags are used for the respective dialog
 771 item, the dialog item can be made to fill out the available space
 772 entirely, i.e. it will grow to a size larger than the minimal size, or
 773 it will be moved to either the centre of the available space or to
 774 either side of the space.  The following sample shows a listbox and
 775 three buttons in a horizontal box sizer; one button is centred, one is
 776 aligned at the top, one is aligned at the bottom:</p>
 777 <p>[Need graphics]</p>
 778 </div>
 779 <div class="section">
 780 <h3><a class="toc-backref" href="#id21" id="a-stretch-factor" name="a-stretch-factor">A stretch factor</a></h3>
 781 <p>If a sizer contains more than one child and it is offered more space
 782 than its children and their borders need, the question arises how to
 783 distribute the surplus space among the children.  For this purpose, a
 784 stretch factor may be assigned to each child, where the default value
 785 of 0 indicates that the child will not get more space than its
 786 requested minimum size.  A value of more than zero is interpreted in
 787 relation to the sum of all stretch factors in the children of the
 788 respective sizer, i.e. if two children get a stretch factor of 1, they
 789 will get half the extra space each independent of whether one control
 790 has a minimal sizer inferior to the other or not.  The following
 791 sample shows a dialog with three buttons, the first one has a stretch
 792 factor of 1 and thus gets stretched, whereas the other two buttons
 793 have a stretch factor of zero and keep their initial width:</p>
 794 <p>[Need graphics]</p>
 795 <p>Within wxDesigner, this stretch factor gets set from the Option menu.</p>
 796 </div>
 797 </div>
 798 <div class="section">
 799 <h2><a class="toc-backref" href="#id22" id="boxsizer" name="boxsizer">BoxSizer</a></h2>
 800 <p>BoxSizer can lay out its children either vertically or horizontally,
 801 depending on what flag is being used in its constructor.  When using a
 802 vertical sizer, each child can be centered, aligned to the right or
 803 aligned to the left.  Correspondingly, when using a horizontal sizer,
 804 each child can be centered, aligned at the bottom or aligned at the
 805 top.  The stretch factor described in the last paragraph is used for
 806 the main orientation, i.e. when using a horizontal box sizer, the
 807 stretch factor determines how much the child can be stretched
 808 horizontally.  The following sample shows the same dialog as in the
 809 last sample, only the box sizer is a vertical box sizer now:</p>
 810 <p>[Need graphics]</p>
 811 </div>
 812 <div class="section">
 813 <h2><a class="toc-backref" href="#id23" id="staticboxsizer" name="staticboxsizer">StaticBoxSizer</a></h2>
 814 <p>StaticBoxSixer is the same as a BoxSizer, but surrounded by a static
 815 box.  Here is a sample:</p>
 816 <p>[Need graphics]</p>
 817 </div>
 818 <div class="section">
 819 <h2><a class="toc-backref" href="#id24" id="gridsizer" name="gridsizer">GridSizer</a></h2>
 820 <p>GridSizer is a two-dimensional sizer.  All children are given the same
 821 size, which is the minimal size required by the biggest child, in this
 822 case the text control in the left bottom border.  Either the number of
 823 columns or the number or rows is fixed and the grid sizer will grow in
 824 the respectively other orientation if new children are added:</p>
 825 <p>[Need graphics]</p>
 826 </div>
 827 <div class="section">
 828 <h2><a class="toc-backref" href="#id25" id="flexgridsizer" name="flexgridsizer">FlexGridSizer</a></h2>
 829 <p>Another two-dimensional sizer derived from GridSizer.  The width of
 830 each column and the height of each row are calculated individually
 831 according the minimal requirements from the respectively biggest
 832 child.  Additionally, columns and rows can be declared to be
 833 stretchable if the sizer is assigned a size different from that which
 834 it requested.  The following sample shows the same dialog as the one
 835 above, but using a flex grid sizer:</p>
 836 <p>[Need graphics]</p>
 837 </div>
 838 <div class="section">
 839 <h2><a class="toc-backref" href="#id26" id="notebooksizer" name="notebooksizer">NotebookSizer</a></h2>
 840 <p>NotebookSizer can be used with notebooks.  It calculates the size of
 841 each notebook page and sets the size of the notebook to the size of
 842 the biggest page plus some extra space required for the notebook tabs
 843 and decorations.</p>
 844 <p>[Need graphics]</p>
 845 </div>
 846 <div class="section">
 847 <h2><a class="toc-backref" href="#id27" id="programming-with-boxsizer" name="programming-with-boxsizer">Programming with BoxSizer</a></h2>
 848 <p>The basic idea behind a BoxSizer is that windows will most often be
 849 laid out in rather simple basic geometry, typically in a row or a
 850 column or several hierarchies of either.</p>
 851 <p>As an example, we will construct a dialog that will contain a text
 852 field at the top and two buttons at the bottom.  This can be seen as a
 853 top-hierarchy column with the text at the top and buttons at the
 854 bottom and a low-hierarchy row with an OK button to the left and a
 855 Cancel button to the right.  In many cases (particularly dialogs under
 856 Unix and normal frames) the main window will be resizable by the user
 857 and this change of size will have to get propagated to its children.
 858 In our case, we want the text area to grow with the dialog, whereas
 859 the button shall have a fixed size.  In addition, there will be a thin
 860 border around all controls to make the dialog look nice and - to make
 861 matter worse - the buttons shall be centred as the width of the dialog
 862 changes.</p>
 863 <p>It is the unique feature of a box sizer, that it can grow in both
 864 directions (height and width) but can distribute its growth in the
 865 main direction (horizontal for a row) unevenly among its children.  In
 866 our example case, the vertical sizer is supposed to propagate all its
 867 height changes to only the text area, not to the button area.  This is
 868 determined by the proportion parameter when adding a window (or
 869 another sizer) to a sizer.  It is interpreted as a weight factor,
 870 i.e. it can be zero, indicating that the window may not be resized at
 871 all, or above zero.  If several windows have a value above zero, the
 872 value is interpreted relative to the sum of all weight factors of the
 873 sizer, so when adding two windows with a value of 1, they will both
 874 get resized equally much and each half as much as the sizer owning
 875 them.</p>
 876 <p>Then what do we do when a column sizer changes its width?  This
 877 behaviour is controlled by flags (the second parameter of the Add()
 878 function): zero or no flag indicates that the window will preserve it
 879 is original size, wx.GROW flag (same as wx.EXPAND) forces the window
 880 to grow with the sizer, and wx.SHAPED flag tells the window to change
 881 it is size proportionally, preserving original aspect ratio.  When
 882 wx.GROW flag is not used, the item can be aligned within available
 883 space.  wx.ALIGN_LEFT, wx.ALIGN_TOP, wx.ALIGN_RIGHT, wx.ALIGN_BOTTOM,
 884 wx.ALIGN_CENTER_HORIZONTAL and wx.ALIGN_CENTER_VERTICAL do what they
 885 say.  wx.ALIGN_CENTRE (same as wx.ALIGN_CENTER) is defined as
 886 (<tt class="docutils literal"><span class="pre">wx.ALIGN_CENTER_HORIZONTAL</span> <span class="pre">|</span> <span class="pre">wx.ALIGN_CENTER_VERTICAL</span></tt>).  Default
 887 alignment is <tt class="docutils literal"><span class="pre">wx.ALIGN_LEFT</span> <span class="pre">|</span> <span class="pre">wx.ALIGN_TOP</span></tt>.</p>
 888 <p>As mentioned above, any window belonging to a sizer may have border,
 889 and it can be specified which of the four sides may have this border,
 890 using the wx.TOP, wx.LEFT, wx.RIGHT and wx.BOTTOM constants or wx.ALL
 891 for all directions (and you may also use wx.NORTH, wx.WEST etc
 892 instead).  These flags can be used in combination with the alignment
 893 flags above as the second parameter of the Add() method using the
 894 binary or operator (<tt class="docutils literal"><span class="pre">|</span></tt>).  The sizer of the border also must be made
 895 known, and it is the third parameter in the Add() method.  This means,
 896 that the entire behaviour of a sizer and its children can be
 897 controlled by the three parameters of the Add() method.</p>
 898 <p>[Show code and graphic here.]</p>
 899 </div>
 900 <div class="section">
 901 <h2><a class="toc-backref" href="#id28" id="programming-with-gridsizer" name="programming-with-gridsizer">Programming with GridSizer</a></h2>
 902 <p>GridSizer is a sizer which lays out its children in a two-dimensional
 903 table with all table fields having the same size, i.e. the width of
 904 each field is the width of the widest child, the height of each field
 905 is the height of the tallest child.</p>
 906 <p>[Show code and graphic here.]</p>
 907 </div>
 908 <div class="section">
 909 <h2><a class="toc-backref" href="#id29" id="programming-with-flexgridsizer" name="programming-with-flexgridsizer">Programming with FlexGridSizer</a></h2>
 910 <p>FlexGridSizer is a sizer which lays out its children in a
 911 two-dimensional table with all table fields in one row having the same
 912 height and all fields in one column having the same width, but all
 913 rows or all columns are not necessarily the same height or width as in
 914 the GridSizer.</p>
 915 <p>[Show code and graphic here.]</p>
 916 </div>
 917 <div class="section">
 918 <h2><a class="toc-backref" href="#id30" id="programming-with-notebooksizer" name="programming-with-notebooksizer">Programming with NotebookSizer</a></h2>
 919 <p>NotebookSizer is a specialized sizer to make sizers work in connection
 920 with using notebooks.  This sizer is different from any other sizer as
 921 you must not add any children to it - instead, it queries the notebook
 922 class itself.  The only thing this sizer does is to determine the size
 923 of the biggest page of the notebook and report an adjusted minimal
 924 size to a more toplevel sizer.</p>
 925 <p>In order to query the size of notebook page, this page needs to have
 926 its own sizer, otherwise the NotebookSizer will ignore it.  Notebook
 927 pages get their sizer by assigning one to them using SetSizer() and
 928 setting the auto-layout option to True using SetAutoLayout().  Here is
 929 one example showing how to add a notebook page that the notebook sizer
 930 is aware of:</p>
 931 <p>[Show code and graphic here.]</p>
 932 </div>
 933 <div class="section">
 934 <h2><a class="toc-backref" href="#id31" id="programming-with-staticboxsizer" name="programming-with-staticboxsizer">Programming with StaticBoxSizer</a></h2>
 935 <p>StaticBoxSizer is a sizer derived from BoxSizer but adds a static box
 936 around the sizer.  Note that this static box has to be created
 937 separately.</p>
 938 <p>[Show code and graphic here.]</p>
 939 </div>
 940 <div class="section">
 941 <h2><a class="toc-backref" href="#id32" id="dialog-createbuttonsizer" name="dialog-createbuttonsizer">Dialog.CreateButtonSizer</a></h2>
 942 <p>As a convenience, the Dialog class has a CreateButtonSizer(flags)
 943 method that can be used to create a standard button sizer in which
 944 standard buttons are displayed.  The following flags can be passed to
 945 this method:</p>
 946 <table border="1" class="docutils">
 947 <colgroup>
 948 <col width="19%" />
 949 <col width="81%" />
 950 </colgroup>
 951 <tbody valign="top">
 952 <tr><td>wx.YES_NO</td>
 953 <td>add Yes/No subpanel</td>
 954 </tr>
 955 <tr><td>wx.YES</td>
 956 <td>return wx.ID_YES</td>
 957 </tr>
 958 <tr><td>wx.NO</td>
 959 <td>return wx.ID_NO</td>
 960 </tr>
 961 <tr><td>wx.NO_DEFAULT</td>
 962 <td>make the wx.NO button the default, otherwise wx.YES or
 963 wx.OK button will be default</td>
 964 </tr>
 965 <tr><td>wx.OK</td>
 966 <td>return wx.ID_OK</td>
 967 </tr>
 968 <tr><td>wx.CANCEL</td>
 969 <td>return wx.ID_CANCEL</td>
 970 </tr>
 971 <tr><td>wx.HELP</td>
 972 <td>return wx.ID_HELP</td>
 973 </tr>
 974 <tr><td>wx.FORWARD</td>
 975 <td>return wx.ID_FORWARD</td>
 976 </tr>
 977 <tr><td>wx.BACKWARD</td>
 978 <td>return wx.ID_BACKWARD</td>
 979 </tr>
 980 <tr><td>wx.SETUP</td>
 981 <td>return wx.ID_SETUP</td>
 982 </tr>
 983 <tr><td>wx.MORE</td>
 984 <td>return wx.ID_MORE</td>
 985 </tr>
 986 </tbody>
 987 </table>
 988 </div>
 989 </div>
 990 <div class="section">
 991 <h1><a class="toc-backref" href="#id33" id="date-and-time-classes-overview" name="date-and-time-classes-overview">Date and time classes overview</a></h1>
 992 <p>wxPython provides a set of powerful classes to work with dates and
 993 times.  Some of the supported features of the DateTime class are:</p>
 994 <table border="1" class="docutils">
 995 <colgroup>
 996 <col width="18%" />
 997 <col width="82%" />
 998 </colgroup>
 999 <tbody valign="top">
1000 <tr><td>Wide range</td>
1001 <td>The range of supported dates goes from about 4714 B.C. to
1002 some 480 million years in the future.</td>
1003 </tr>
1004 <tr><td>Precision</td>
1005 <td>Not using floating point calculations anywhere ensures that
1006 the date calculations don't suffer from rounding
1007 errors.</td>
1008 </tr>
1009 <tr><td>Many features</td>
1010 <td>Not only all usual calculations with dates are
1011 supported, but also more exotic week and year day
1012 calculations, work day testing, standard astronomical
1013 functions, conversion to and from strings in either
1014 strict or free format.</td>
1015 </tr>
1016 <tr><td>Efficiency</td>
1017 <td>Objects of DateTime are small (8 bytes) and working
1018 with them is fast</td>
1019 </tr>
1020 </tbody>
1021 </table>
1022 <div class="section">
1023 <h2><a class="toc-backref" href="#id34" id="all-date-time-classes-at-a-glance" name="all-date-time-classes-at-a-glance">All date/time classes at a glance</a></h2>
1024 <p>There are 3 main classes: except DateTime itself which represents an
1025 absolute moment in time, there are also two classes - TimeSpan and
1026 DateSpan which represent the intervals of time.</p>
1027 <p>There are also helper classes which are used together with DateTime:
1028 DateTimeHolidayAuthority which is used to determine whether a given
1029 date is a holiday or not and DateTimeWorkDays which is a derivation of
1030 this class for which (only) Saturdays and Sundays are the holidays.
1031 See more about these classes in the discussion of the holidays.</p>
1032 </div>
1033 <div class="section">
1034 <h2><a class="toc-backref" href="#id35" id="datetime-characteristics" name="datetime-characteristics">DateTime characteristics</a></h2>
1035 <p>DateTime stores the time as a signed number of milliseconds since the
1036 Epoch which is fixed, by convention, to Jan 1, 1970 - however this is
1037 not visible to the class users (in particular, dates prior to the
1038 Epoch are handled just as well (or as bad) as the dates after it).
1039 But it does mean that the best resolution which can be achieved with
1040 this class is 1 millisecond.</p>
1041 <p>The size of DateTime object is 8 bytes because it is represented as a
1042 64 bit integer.  The resulting range of supported dates is thus
1043 approximatively 580 million years, but due to the current limitations
1044 in the Gregorian calendar support, only dates from Nov 24, 4714BC are
1045 supported (this is subject to change if there is sufficient interest
1046 in doing it).</p>
1047 <p>Finally, the internal representation is time zone independent (always
1048 in GMT) and the time zones only come into play when a date is broken
1049 into year/month/day components. See more about timezones below.</p>
1050 <p>Currently, the only supported calendar is Gregorian one (which is used
1051 even for the dates prior to the historic introduction of this calendar
1052 which was first done on Oct 15, 1582 but is, generally speaking,
1053 country, and even region, dependent).  Future versions will probably
1054 have Julian calendar support as well and support for other calendars
1055 (Maya, Hebrew, Chinese...) is not ruled out.</p>
1056 </div>
1057 <div class="section">
1058 <h2><a class="toc-backref" href="#id36" id="difference-between-datespan-and-timespan" name="difference-between-datespan-and-timespan">Difference between DateSpan and TimeSpan</a></h2>
1059 <p>While there is only one logical way to represent an absolute moment in
1060 the time (and hence only one DateTime class), there are at least two
1061 methods to describe a time interval.</p>
1062 <p>First, there is the direct and self-explaining way implemented by
1063 TimeSpan: it is just a difference in milliseconds between two moments
1064 in time.  Adding or subtracting such an interval to DateTime is always
1065 well-defined and is a fast operation.</p>
1066 <p>But in daily life other, calendar-dependent time interval
1067 specifications are used.  For example, 'one month later' is commonly
1068 used.  However, it is clear that this is not the same as TimeSpan of
1069 60*60*24*31 seconds because 'one month later' Feb 15 is Mar 15 and not
1070 Mar 17 or Mar 16 (depending on whether the year is leap or not).</p>
1071 <p>This is why there is another class for representing such intervals
1072 called DateSpan.  It handles these sort of operations in the most
1073 natural way possible, but note that manipulating with intervals of
1074 this kind is not always well-defined.  Consider, for example, Jan 31 +
1075 '1 month': this will give Feb 28 (or 29), i.e. the last day of
1076 February and not the non-existent Feb 31.  Of course, this is what is
1077 usually wanted, but you still might be surprised to notice that now
1078 subtracting back the same interval from Feb 28 will result in Jan 28
1079 and not Jan 31 we started with!</p>
1080 <p>So, unless you plan to implement some kind of natural language parsing
1081 in the program, you should probably use TimeSpan instead of DateSpan
1082 (which is also more efficient).  However, DateSpan may be very useful
1083 in situations when you do need to understand what 'in a month' means
1084 (of course, it is just DateTime.Now() + DateSpan.Month()).</p>
1085 </div>
1086 <div class="section">
1087 <h2><a class="toc-backref" href="#id37" id="date-arithmetics" name="date-arithmetics">Date arithmetics</a></h2>
1088 <p>Many different operations may be performed with the dates, however not
1089 all of them make sense.  For example, multiplying a date by a number
1090 is an invalid operation, even though multiplying either of the time
1091 span classes by a number is perfectly valid.</p>
1092 <p>Here is what can be done:</p>
1093 <table border="1" class="docutils">
1094 <colgroup>
1095 <col width="19%" />
1096 <col width="81%" />
1097 </colgroup>
1098 <tbody valign="top">
1099 <tr><td>Addition</td>
1100 <td>a TimeSpan or DateSpan can be added to DateTime resulting in
1101 a new DateTime object and also 2 objects of the same
1102 span class can be added together giving another object
1103 of the same class.</td>
1104 </tr>
1105 <tr><td>Subtraction</td>
1106 <td>the same types of operations as above are allowed and,
1107 additionally, a difference between two DateTime
1108 objects can be taken and this will yield TimeSpan.</td>
1109 </tr>
1110 <tr><td>Multiplication</td>
1111 <td>a TimeSpan or DateSpan object can be multiplied by an
1112 integer number resulting in an object of the same
1113 type.</td>
1114 </tr>
1115 <tr><td>Unary minus</td>
1116 <td>a TimeSpan or DateSpan object may finally be negated
1117 giving an interval of the same magnitude but of
1118 opposite time direction.</td>
1119 </tr>
1120 </tbody>
1121 </table>
1122 </div>
1123 <div class="section">
1124 <h2><a class="toc-backref" href="#id38" id="time-zone-considerations" name="time-zone-considerations">Time zone considerations</a></h2>
1125 <p>Although the time is always stored internally in GMT, you will usually
1126 work in the local time zone.  Because of this, all DateTime
1127 constructors and setters which take the broken down date assume that
1128 these values are for the local time zone.  Thus, DateTime(1,
1129 DateTime.Jan, 1970) will not correspond to the DateTime Epoch unless
1130 you happen to live in the UK.</p>
1131 <p>All methods returning the date components (year, month, day, hour,
1132 minute, second...) will also return the correct values for the local
1133 time zone by default.  So, generally, doing the natural things will
1134 lead to natural and correct results.</p>
1135 <p>If you only want to do this, you may safely skip the rest of this
1136 section.  However, if you want to work with different time zones, you
1137 should read it to the end.</p>
1138 <p>In this (rare) case, you are still limited to the local time zone when
1139 constructing DateTime objects, i.e. there is no way to construct a
1140 DateTime corresponding to the given date in, say, Pacific Standard
1141 Time.  To do it, you will need to call ToTimezone or MakeTimezone
1142 methods to adjust the date for the target time zone.  There are also
1143 special versions of these functions ToGMT and MakeGMT for the most
1144 common case - when the date should be constructed in GMT.</p>
1145 <p>You also can just retrieve the value for some time zone without
1146 converting the object to it first.  For this you may pass TimeZone
1147 argument to any of the methods which are affected by the time zone
1148 (all methods getting date components and the date formatting ones, for
1149 example).  In particular, the Format() family of methods accepts a
1150 TimeZone parameter and this allows to simply print time in any time
1151 zone.</p>
1152 <p>To see how to do it, the last issue to address is how to construct a
1153 TimeZone object which must be passed to all these methods. First of
1154 all, you may construct it manually by specifying the time zone offset
1155 in seconds from GMT, but usually you will just use one of the symbolic
1156 time zone names and let the conversion constructor do the
1157 job. I.e. you would just write</p>
1158 <p>wxDateTime dt(...whatever...);
1159 printf(&quot;The time is %s in local time zone&quot;, dt.FormatTime().c_str());
1160 printf(&quot;The time is %s in GMT&quot;, dt.FormatTime(wxDateTime::GMT).c_str());</p>
1161 </div>
1162 <div class="section">
1163 <h2><a class="toc-backref" href="#id39" id="daylight-saving-time-dst" name="daylight-saving-time-dst">Daylight saving time (DST)</a></h2>
1164 <p>DST (a.k.a. 'summer time') handling is always a delicate task which is
1165 better left to the operating system which is supposed to be configured
1166 by the administrator to behave correctly.  Unfortunately, when doing
1167 calculations with date outside of the range supported by the standard
1168 library, we are forced to deal with these issues ourselves.</p>
1169 <p>Several functions are provided to calculate the beginning and end of
1170 DST in the given year and to determine whether it is in effect at the
1171 given moment or not, but they should not be considered as absolutely
1172 correct because, first of all, they only work more or less correctly
1173 for only a handful of countries (any information about other ones
1174 appreciated!) and even for them the rules may perfectly well change in
1175 the future.</p>
1176 <p>The time zone handling methods use these functions too, so they are
1177 subject to the same limitations.</p>
1178 </div>
1179 <div class="section">
1180 <h2><a class="toc-backref" href="#id40" id="datetime-and-holidays" name="datetime-and-holidays">DateTime and Holidays</a></h2>
1181 <p>[TODO]</p>
1182 </div>
1183 </div>
1184 <div class="section">
1185 <h1><a class="toc-backref" href="#id41" id="classes-by-category" name="classes-by-category">Classes by category</a></h1>
1186 <p>Not done yet.</p>
1187 </div>
1188 <div class="section">
1189 <h1><a class="toc-backref" href="#id42" id="id-constants" name="id-constants">ID constants</a></h1>
1190 <p>wxPython provides the following predefined ID constants:</p>
1191 <p>ID_ABORT
1192 ID_ABOUT
1193 ID_ANY
1194 ID_APPLY
1195 ID_BACKWARD
1196 ID_CANCEL
1197 ID_CLEAR
1198 ID_CLOSE
1199 ID_CLOSE_ALL
1200 ID_CONTEXT_HELP
1201 ID_COPY
1202 ID_CUT
1203 ID_DEFAULT
1204 ID_DUPLICATE
1205 ID_EXIT
1206 ID_FILE1
1207 ID_FILE2
1208 ID_FILE3
1209 ID_FILE4
1210 ID_FILE5
1211 ID_FILE6
1212 ID_FILE7
1213 ID_FILE8
1214 ID_FILE9
1215 ID_FILTERLISTCTRL
1216 ID_FIND
1217 ID_FORWARD
1218 ID_HELP
1219 ID_HELP_COMMANDS
1220 ID_HELP_CONTENTS
1221 ID_HELP_CONTEXT
1222 ID_HELP_PROCEDURES
1223 ID_IGNORE
1224 ID_MORE
1225 ID_NEW
1226 ID_NO
1227 ID_NOTOALL
1228 ID_OK
1229 ID_OPEN
1230 ID_PASTE
1231 ID_PREVIEW
1232 ID_PRINT
1233 ID_PRINT_SETUP
1234 ID_REDO
1235 ID_RESET
1236 ID_RETRY
1237 ID_REVERT
1238 ID_SAVE
1239 ID_SAVEAS
1240 ID_SELECTALL
1241 ID_SEPARATOR
1242 ID_SETUP
1243 ID_STATIC
1244 ID_TREECTRL
1245 ID_UNDO
1246 ID_YES
1247 ID_YESTOALL</p>
1248 </div>
1249 <div class="section">
1250 <h1><a class="toc-backref" href="#id43" id="source-document" name="source-document">Source document</a></h1>
1251 <p>The source document is named wxPythonManual.txt and can be found by
1252 clicking the link at the bottom of this page (assuming you are viewing
1253 the html file).  It is written using a fantastic formatting convention
1254 called reStructuredText.  The wxPythonManual.html file is created
1255 using the Docutils utilities, which can turn reStructuredText
1256 documents into html, xml, pdf, and even OpenOffice files.</p>
1257 </div>
1258 <div class="section">
1259 <h1><a class="toc-backref" href="#id44" id="submitting-changes-to-the-source-document" name="submitting-changes-to-the-source-document">Submitting changes to the source document</a></h1>
1260 <p>Some items in the source text file look like this:</p>
1261 <pre class="literal-block">
1262 .. This is text from the wxWidgets documentation that needs to be
1263    translated into something appropriate for the wxPython version.
1264    The two dots followed by uniformly indented text turns this
1265    paragraph into a reStructuredText comment, so it doesn't appear
1266    in any output file, such as the html file.
1267 </pre>
1268 <p>They have been commented out and are awaiting editorial review and a
1269 rewrite so that they make sense in the context of wxPython.  Feel free
1270 to send me suggestions for rewording these, or any other parts of this
1271 document that you think need improving.  I will be eternally grateful
1272 to you and will show my gratitude by adding your name to the list of
1273 contributors.  (Contributors who also send me gifts of coffee,
1274 chocolate, or currency will have their names listed in bold.)</p>
1275 </div>
1276 <div class="section">
1277 <h1><a class="toc-backref" href="#id45" id="contributors" name="contributors">Contributors</a></h1>
1278 <p>Individuals who contributed to this documentation (in order by last
1279 name):</p>
1280 <ul class="simple">
1281 <li>Robin Dunn</li>
1282 <li>Patrick K. O'Brien</li>
1283 <li>Robert Roebling</li>
1284 <li>Julian Smart</li>
1285 <li>Vadim Zeitlin</li>
1286 </ul>
1287 </div>
1288 <div class="section">
1289 <h1><a class="toc-backref" href="#id46" id="license" name="license">License</a></h1>
1290 <p>This document began as a translation of the wxWidgets documentation.
1291 As such, it adheres to the same license, which is provided here:</p>
1292 <pre class="literal-block">
1293                 wxWindows Free Documentation Licence, Version 3
1294                 ===============================================
1295
1296   Copyright (c) 1998 Julian Smart, Robert Roebling et al
1297
1298   Everyone is permitted to copy and distribute verbatim copies
1299   of this licence document, but changing it is not allowed.
1300
1301                    WXWINDOWS FREE DOCUMENTATION LICENCE
1302      TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
1303
1304   1. Permission is granted to make and distribute verbatim copies of this
1305   manual or piece of documentation provided any copyright notice and this
1306   permission notice are preserved on all copies.
1307
1308   2. Permission is granted to process this file or document through a
1309   document processing system and, at your option and the option of any third
1310   party, print the results, provided a printed document carries a copying
1311   permission notice identical to this one.
1312
1313   3. Permission is granted to copy and distribute modified versions of this
1314   manual or piece of documentation under the conditions for verbatim
1315   copying, provided also that any sections describing licensing conditions
1316   for this manual, such as, in particular, the GNU General Public Licence,
1317   the GNU Library General Public Licence, and any wxWindows Licence are
1318   included exactly as in the original, and provided that the entire
1319   resulting derived work is distributed under the terms of a permission
1320   notice identical to this one.
1321
1322   4. Permission is granted to copy and distribute translations of this
1323   manual or piece of documentation into another language, under the above
1324   conditions for modified versions, except that sections related to
1325   licensing, including this paragraph, may also be included in translations
1326   approved by the copyright holders of the respective licence documents in
1327   addition to the original English.
1328
1329                             WARRANTY DISCLAIMER
1330
1331   5. BECAUSE THIS MANUAL OR PIECE OF DOCUMENTATION IS LICENSED FREE OF CHARGE,
1332   THERE IS NO WARRANTY FOR IT, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
1333   EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER
1334   PARTIES PROVIDE THIS MANUAL OR PIECE OF DOCUMENTATION &quot;AS IS&quot; WITHOUT
1335   WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT
1336   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
1337   PARTICULAR PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF
1338   THE MANUAL OR PIECE OF DOCUMENTATION IS WITH YOU.  SHOULD THE MANUAL OR
1339   PIECE OF DOCUMENTATION PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
1340   NECESSARY SERVICING, REPAIR OR CORRECTION.
1341
1342   6. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL
1343   ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
1344   REDISTRIBUTE THE MANUAL OR PIECE OF DOCUMENTATION AS PERMITTED ABOVE, BE
1345   LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
1346   CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
1347   MANUAL OR PIECE OF DOCUMENTATION (INCLUDING BUT NOT LIMITED TO LOSS OF
1348   DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
1349   PARTIES OR A FAILURE OF A PROGRAM BASED ON THE MANUAL OR PIECE OF
1350   DOCUMENTATION TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR
1351   OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
1352
1353
1354 </pre>
1355 </div>
1356 </div>
1357 </body>
1358 </html>