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