709d7afa23
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@43711 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
1077 lines
55 KiB
HTML
1077 lines
55 KiB
HTML
<?xml version="1.0" encoding="iso-8859-1" ?>
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
|
|
<meta name="generator" content="Docutils 0.4.1: http://docutils.sourceforge.net/" />
|
|
<title>The wxPython Manual</title>
|
|
<meta name="author" content="Patrick K. O'Brien" />
|
|
<meta name="organization" content="Orbtech" />
|
|
<meta name="date" content="2004-03-26" />
|
|
<link rel="stylesheet" href="default.css" type="text/css" />
|
|
</head>
|
|
<body>
|
|
<div class="document" id="the-wxpython-manual">
|
|
<h1 class="title">The wxPython Manual</h1>
|
|
<h2 class="subtitle" id="a-guide-to-wxpython-for-python-programmers">A guide to wxPython for Python programmers</h2>
|
|
<table class="docinfo" frame="void" rules="none">
|
|
<col class="docinfo-name" />
|
|
<col class="docinfo-content" />
|
|
<tbody valign="top">
|
|
<tr><th class="docinfo-name">Author:</th>
|
|
<td>Patrick K. O'Brien</td></tr>
|
|
<tr><th class="docinfo-name">Contact:</th>
|
|
<td><a class="first last reference" href="mailto:pobrien@orbtech.com">pobrien@orbtech.com</a></td></tr>
|
|
<tr><th class="docinfo-name">Organization:</th>
|
|
<td><a class="first last reference" href="http://www.orbtech.com/">Orbtech</a></td></tr>
|
|
<tr><th class="docinfo-name">Date:</th>
|
|
<td>2004-03-26</td></tr>
|
|
<tr><th class="docinfo-name">Revision:</th>
|
|
<td>1.3</td></tr>
|
|
<tr class="field"><th class="docinfo-name">License:</th><td class="field-body">wxWindows Free Documentation Licence, Version 3</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<div class="contents topic">
|
|
<p class="topic-title first"><a id="contents" name="contents">Contents</a></p>
|
|
<ul class="simple">
|
|
<li><a class="reference" href="#introduction" id="id1" name="id1">Introduction</a></li>
|
|
<li><a class="reference" href="#what-is-wxpython" id="id2" name="id2">What is wxPython?</a></li>
|
|
<li><a class="reference" href="#wxpython-requirements" id="id3" name="id3">wxPython requirements</a><ul>
|
|
<li><a class="reference" href="#ms-windows" id="id4" name="id4">MS-Windows</a></li>
|
|
<li><a class="reference" href="#linux-or-unix" id="id5" name="id5">Linux or Unix</a></li>
|
|
<li><a class="reference" href="#mac-os-x" id="id6" name="id6">Mac OS X</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="reference" href="#what-is-wxwidgets" id="id7" name="id7">What is wxWidgets?</a></li>
|
|
<li><a class="reference" href="#why-another-cross-platform-development-tool" id="id8" name="id8">Why another cross-platform development tool?</a></li>
|
|
<li><a class="reference" href="#wxpython-overview" id="id9" name="id9">wxPython Overview</a></li>
|
|
<li><a class="reference" href="#utilities-and-libraries-supplied-with-wxpython" id="id10" name="id10">Utilities and libraries supplied with wxPython</a></li>
|
|
<li><a class="reference" href="#creating-and-deleting-wxpython-objects" id="id11" name="id11">Creating and deleting wxPython objects</a></li>
|
|
<li><a class="reference" href="#app-overview" id="id12" name="id12">App overview</a><ul>
|
|
<li><a class="reference" href="#application-initialization" id="id13" name="id13">Application initialization</a></li>
|
|
<li><a class="reference" href="#application-shutdown" id="id14" name="id14">Application shutdown</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="reference" href="#sizer-overview" id="id15" name="id15">Sizer overview</a><ul>
|
|
<li><a class="reference" href="#the-idea-behind-sizers" id="id16" name="id16">The idea behind sizers</a></li>
|
|
<li><a class="reference" href="#common-features" id="id17" name="id17">Common features</a><ul>
|
|
<li><a class="reference" href="#a-minimal-size" id="id18" name="id18">A minimal size</a></li>
|
|
<li><a class="reference" href="#a-border" id="id19" name="id19">A border</a></li>
|
|
<li><a class="reference" href="#an-alignment" id="id20" name="id20">An alignment</a></li>
|
|
<li><a class="reference" href="#a-stretch-factor" id="id21" name="id21">A stretch factor</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="reference" href="#boxsizer" id="id22" name="id22">BoxSizer</a></li>
|
|
<li><a class="reference" href="#staticboxsizer" id="id23" name="id23">StaticBoxSizer</a></li>
|
|
<li><a class="reference" href="#gridsizer" id="id24" name="id24">GridSizer</a></li>
|
|
<li><a class="reference" href="#flexgridsizer" id="id25" name="id25">FlexGridSizer</a></li>
|
|
<li><a class="reference" href="#notebooksizer" id="id26" name="id26">NotebookSizer</a></li>
|
|
<li><a class="reference" href="#programming-with-boxsizer" id="id27" name="id27">Programming with BoxSizer</a></li>
|
|
<li><a class="reference" href="#programming-with-gridsizer" id="id28" name="id28">Programming with GridSizer</a></li>
|
|
<li><a class="reference" href="#programming-with-flexgridsizer" id="id29" name="id29">Programming with FlexGridSizer</a></li>
|
|
<li><a class="reference" href="#programming-with-notebooksizer" id="id30" name="id30">Programming with NotebookSizer</a></li>
|
|
<li><a class="reference" href="#programming-with-staticboxsizer" id="id31" name="id31">Programming with StaticBoxSizer</a></li>
|
|
<li><a class="reference" href="#dialog-createbuttonsizer" id="id32" name="id32">Dialog.CreateButtonSizer</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="reference" href="#date-and-time-classes-overview" id="id33" name="id33">Date and time classes overview</a><ul>
|
|
<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>
|
|
<li><a class="reference" href="#datetime-characteristics" id="id35" name="id35">DateTime characteristics</a></li>
|
|
<li><a class="reference" href="#difference-between-datespan-and-timespan" id="id36" name="id36">Difference between DateSpan and TimeSpan</a></li>
|
|
<li><a class="reference" href="#date-arithmetics" id="id37" name="id37">Date arithmetics</a></li>
|
|
<li><a class="reference" href="#time-zone-considerations" id="id38" name="id38">Time zone considerations</a></li>
|
|
<li><a class="reference" href="#daylight-saving-time-dst" id="id39" name="id39">Daylight saving time (DST)</a></li>
|
|
<li><a class="reference" href="#datetime-and-holidays" id="id40" name="id40">DateTime and Holidays</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="reference" href="#classes-by-category" id="id41" name="id41">Classes by category</a></li>
|
|
<li><a class="reference" href="#id-constants" id="id42" name="id42">ID constants</a></li>
|
|
<li><a class="reference" href="#source-document" id="id43" name="id43">Source document</a></li>
|
|
<li><a class="reference" href="#submitting-changes-to-the-source-document" id="id44" name="id44">Submitting changes to the source document</a></li>
|
|
<li><a class="reference" href="#contributors" id="id45" name="id45">Contributors</a></li>
|
|
<li><a class="reference" href="#license" id="id46" name="id46">License</a></li>
|
|
</ul>
|
|
</div>
|
|
<div class="section">
|
|
<h1><a class="toc-backref" href="#id1" id="introduction" name="introduction">Introduction</a></h1>
|
|
<p>This is a guide to the wxPython GUI toolkit, written <strong>by</strong> a Python
|
|
programmer <strong>for</strong> his fellow Python programmers. It began as a
|
|
simple translation of the wxWidgets documentation (which is written
|
|
for C++ programmers), and evolved from there. And while there's
|
|
nothing wrong with C++...</p>
|
|
<p>Okay, you got me there. I hate C++. That's why I use Python. If you
|
|
like C++, go read the wxWidgets documentation. If you'd rather read a
|
|
guide that's written with Python programmers in mind, keep reading
|
|
this one. If you like it, feel free to send me freshly roasted coffee
|
|
beans, dark chocolate, and large denomination currency. Better yet,
|
|
buy huge quantities of my wxPython book (written with Robin Dunn) and
|
|
send one to each of your friends, relatives, and coworkers.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h1><a class="toc-backref" href="#id2" id="what-is-wxpython" name="what-is-wxpython">What is wxPython?</a></h1>
|
|
<p>wxPython is a GUI toolkit for the Python programming language. It
|
|
allows Python programmers to create programs with a robust, highly
|
|
functional graphical user interface, simply and easily. It is
|
|
implemented as a Python extension module (native code) that wraps the
|
|
popular wxWidgets cross platform GUI library, which is written in C++.</p>
|
|
<p>Like Python and wxWidgets, wxPython is Open Source, which means that
|
|
it is free for anyone to use and the source code is available for
|
|
anyone to look at and modify. And anyone can contribute fixes or
|
|
enhnacments to the project.</p>
|
|
<p>wxPython is a cross-platform toolkit. This means that the same
|
|
program will run on multiple platforms without modification.
|
|
Currently supported platforms are 32-bit Microsoft Windows, most Unix
|
|
or unix-like systems, and Macintosh OS X.</p>
|
|
<p>Since the language is Python, wxPython programs are simple, easy to
|
|
write and easy to understand.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h1><a class="toc-backref" href="#id3" id="wxpython-requirements" name="wxpython-requirements">wxPython requirements</a></h1>
|
|
<p>To make use of wxPython, you currently need one of the following
|
|
setups.</p>
|
|
<div class="section">
|
|
<h2><a class="toc-backref" href="#id4" id="ms-windows" name="ms-windows">MS-Windows</a></h2>
|
|
<ul class="simple">
|
|
<li>A 486 or higher PC running MS Windows.</li>
|
|
<li>At least ?? MB of disk space.</li>
|
|
</ul>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a class="toc-backref" href="#id5" id="linux-or-unix" name="linux-or-unix">Linux or Unix</a></h2>
|
|
<ul class="simple">
|
|
<li>Almost any C++ compiler, including GNU C++ (EGCS 1.1.1 or above).</li>
|
|
<li>Almost any Unix workstation, and one of: GTK+ 1.2, GTK+ 2.0, Motif
|
|
1.2 or higher, Lesstif.</li>
|
|
<li>At least ?? MB of disk space.</li>
|
|
</ul>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a class="toc-backref" href="#id6" id="mac-os-x" name="mac-os-x">Mac OS X</a></h2>
|
|
<ul class="simple">
|
|
<li>A PowerPC Mac running Mac OS X 10.x.</li>
|
|
<li>At least ?? MB of disk space.</li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
<div class="section">
|
|
<h1><a class="toc-backref" href="#id7" id="what-is-wxwidgets" name="what-is-wxwidgets">What is wxWidgets?</a></h1>
|
|
<p>wxWidgets is a C++ framework providing GUI (Graphical User Interface)
|
|
and other facilities on more than one platform. Version 2 currently
|
|
supports all desktop versions of MS Windows, Unix with GTK+, Unix with
|
|
Motif, and MacOS. An OS/2 port is in progress.</p>
|
|
<p>wxWidgets was originally developed at the Artificial Intelligence
|
|
Applications Institute, University of Edinburgh, for internal use, and
|
|
was first made publicly available in 1992. Version 2 is a vastly
|
|
improved version written and maintained by Julian Smart, Robert
|
|
Roebling, Vadim Zeitlin, Vaclav Slavik and many others.</p>
|
|
<p>Please note that in the following, "MS Windows" often refers to all
|
|
platforms related to Microsoft Windows, including 16-bit and 32-bit
|
|
variants, unless otherwise stated. All trademarks are acknowledged.</p>
|
|
</div>
|
|
<div class="section">
|
|
<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>
|
|
<p>wxWidgets was developed to provide a cheap and flexible way to
|
|
maximize investment in GUI application development. While a number of
|
|
commercial class libraries already existed for cross-platform
|
|
development, none met all of the following criteria:</p>
|
|
<ul class="simple">
|
|
<li>low price</li>
|
|
<li>source availability</li>
|
|
<li>simplicity of programming</li>
|
|
<li>support for a wide range of compilers</li>
|
|
</ul>
|
|
<p>Since wxWidgets was started, several other free or almost-free GUI
|
|
frameworks have emerged. However, none has the range of features,
|
|
flexibility, documentation and the well-established development team
|
|
that wxWidgets has.</p>
|
|
<p>As open source software, wxWidgets has benefited from comments, ideas,
|
|
bug fixes, enhancements and the sheer enthusiasm of users. This gives
|
|
wxWidgets a certain advantage over its commercial competitors (and
|
|
over free libraries without an independent development team), plus a
|
|
robustness against the transience of one individual or company. This
|
|
openness and availability of source code is especially important when
|
|
the future of thousands of lines of application code may depend upon
|
|
the longevity of the underlying class library.</p>
|
|
<p>Version 2 goes much further than previous versions in terms of
|
|
generality and features, allowing applications to be produced that are
|
|
often indistinguishable from those produced using single-platform
|
|
toolkits such as Motif, GTK+ and MFC.</p>
|
|
<p>The importance of using a platform-independent class library cannot be
|
|
overstated, since GUI application development is very time-consuming,
|
|
and sustained popularity of particular GUIs cannot be guaranteed.
|
|
Code can very quickly become obsolete if it addresses the wrong
|
|
platform or audience. wxWidgets helps to insulate the programmer from
|
|
these winds of change. Although wxWidgets may not be suitable for
|
|
every application (such as an OLE-intensive program), it provides
|
|
access to most of the functionality a GUI program normally requires,
|
|
plus many extras such as network programming, PostScript output, and
|
|
HTML rendering; and it can of course be extended as needs dictate. As
|
|
a bonus, it provides a far cleaner and easier programming interface
|
|
than the native APIs. Programmers may find it worthwhile to use
|
|
wxWidgets even if they are developing on only one platform.</p>
|
|
<p>It is impossible to sum up the functionality of wxWidgets in a few
|
|
paragraphs, but here are some of the benefits:</p>
|
|
<ul class="simple">
|
|
<li>Low cost (free, in fact!)</li>
|
|
<li>You get the source.</li>
|
|
<li>Available on a variety of popular platforms.</li>
|
|
<li>Works with almost all popular C++ compilers and Python.</li>
|
|
<li>Over 50 example programs.</li>
|
|
<li>Over 1000 pages of printable and on-line documentation.</li>
|
|
<li>Includes Tex2RTF, to allow you to produce your own documentation in
|
|
Windows Help, HTML and Word RTF formats.</li>
|
|
<li>Simple-to-use, object-oriented API.</li>
|
|
<li>Flexible event system.</li>
|
|
<li>Graphics calls include lines, rounded rectangles, splines,
|
|
polylines, etc.</li>
|
|
<li>Constraint-based and sizer-based layouts.</li>
|
|
<li>Print/preview and document/view architectures.</li>
|
|
<li>Toolbar, notebook, tree control, advanced list control classes.</li>
|
|
<li>PostScript generation under Unix, normal MS Windows printing on the
|
|
PC.</li>
|
|
<li>MDI (Multiple Document Interface) support.</li>
|
|
<li>Can be used to create DLLs under Windows, dynamic libraries on Unix.</li>
|
|
<li>Common dialogs for file browsing, printing, colour selection, etc.</li>
|
|
<li>Under MS Windows, support for creating metafiles and copying them to
|
|
the clipboard.</li>
|
|
<li>An API for invoking help from applications.</li>
|
|
<li>Ready-to-use HTML window (supporting a subset of HTML).</li>
|
|
<li>Dialog Editor for building dialogs.</li>
|
|
<li>Network support via a family of socket and protocol classes.</li>
|
|
<li>Support for platform independent image processing.</li>
|
|
<li>Built-in support for many file formats (BMP, PNG, JPEG, GIF, XPM,
|
|
PNM, PCX).</li>
|
|
</ul>
|
|
</div>
|
|
<div class="section">
|
|
<h1><a class="toc-backref" href="#id9" id="wxpython-overview" name="wxpython-overview">wxPython Overview</a></h1>
|
|
<p>To set a wxPython application going, you will need to derive an App
|
|
class and override App.OnInit.</p>
|
|
<p>An application must have a top-level Frame or Dialog window. Each
|
|
frame may contain one or more instances of classes such as Panel,
|
|
SplitterWindow or other windows and controls.</p>
|
|
<p>A frame can have a MenuBar, a ToolBar, a status line, and an Icon for
|
|
when the frame is iconized.</p>
|
|
<p>A Panel is used to place controls (classes derived from Control) which
|
|
are used for user interaction. Examples of controls are Button,
|
|
CheckBox, Choice, ListBox, RadioBox, Slider.</p>
|
|
<p>Instances of Dialog can also be used for controls, and they have the
|
|
advantage of not requiring a separate frame.</p>
|
|
<p>Instead of creating a dialog box and populating it with items, it is
|
|
possible to choose one of the convenient common dialog classes, such
|
|
as MessageDialog and FileDialog.</p>
|
|
<p>You never draw directly onto a window. Instead, you use a device
|
|
context (DC). DC is the base for ClientDC, PaintDC, MemoryDC,
|
|
PostScriptDC, MemoryDC, MetafileDC and PrinterDC. If your drawing
|
|
functions have DC as a parameter, you can pass any of these DCs to the
|
|
function, and thus use the same code to draw to several different
|
|
devices. You can draw using the member functions of DC, such as
|
|
DC.DrawLine and DC.DrawText. Control colour on a window (Colour) with
|
|
brushes (Brush) and pens (Pen).</p>
|
|
<!-- To intercept events, you add a DECLARE_EVENT_TABLE macro to the
|
|
window class declaration, and put a BEGIN_EVENT_TABLE
|
|
... END_EVENT_TABLE block in the implementation file. Between these
|
|
macros, you add event macros which map the event (such as a mouse
|
|
click) to a member function. These might override predefined event
|
|
handlers such as for KeyEvent and MouseEvent. -->
|
|
<p>Most modern applications will have an on-line, hypertext help system;
|
|
for this, you need Help and the HelpController class to control
|
|
Help.</p>
|
|
<p>GUI applications aren't all graphical wizardry. You'll also need
|
|
lists and hash tables. But since you're working with Python, you
|
|
should use the ones Python provides (list, tuple, dict), rather than
|
|
the wxWidgets versions. Same goes for the database related classes.
|
|
The basic rule of thumb is this: If you can do it directly in Python,
|
|
you probably should. If there is a reason not to use a Python data
|
|
type, wxPython will provide a wrapper for the wxWidgets class.</p>
|
|
<p>You will undoubtedly need some platform-independent file functions,
|
|
and you may find it handy to maintain and search a list of paths using
|
|
PathList. There's a miscellany of operating system and other
|
|
functions.</p>
|
|
<p>See also Classes by Category for a list of classes.</p>
|
|
</div>
|
|
<div class="section">
|
|
<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>
|
|
<p>In addition to the core wxWidgets library, a number of further
|
|
libraries and utilities are supplied with each distribution.</p>
|
|
<p>[Need to list these.]</p>
|
|
</div>
|
|
<div class="section">
|
|
<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>
|
|
<p>[This section needs to be reviewed.]</p>
|
|
<!-- In general, classes derived from wxWindow must dynamically
|
|
allocated with new and deleted with delete. If you delete a window,
|
|
all of its children and descendants will be automatically deleted,
|
|
so you don't need to delete these descendants explicitly. -->
|
|
<!-- When deleting a frame or dialog, use Destroy rather than delete so
|
|
that the wxWidgets delayed deletion can take effect. This waits
|
|
until idle time (when all messages have been processed) to actually
|
|
delete the window, to avoid problems associated with the GUI
|
|
sending events to deleted windows. -->
|
|
<!-- If you decide to allocate a C++ array of objects (such as wxBitmap)
|
|
that may be cleaned up by wxWidgets, make sure you delete the array
|
|
explicitly before wxWidgets has a chance to do so on exit, since
|
|
calling delete on array members will cause memory problems. -->
|
|
<!-- wxColour can be created statically: it is not automatically cleaned
|
|
up and is unlikely to be shared between other objects; it is
|
|
lightweight enough for copies to be made. -->
|
|
<!-- Beware of deleting objects such as a wxPen or wxBitmap if they are
|
|
still in use. Windows is particularly sensitive to this: so make
|
|
sure you make calls like wxDC::SetPen(wxNullPen) or
|
|
wxDC::SelectObject(wxNullBitmap) before deleting a drawing object
|
|
that may be in use. Code that doesn't do this will probably work
|
|
fine on some platforms, and then fail under Windows. -->
|
|
</div>
|
|
<div class="section">
|
|
<h1><a class="toc-backref" href="#id12" id="app-overview" name="app-overview">App overview</a></h1>
|
|
<p>Classes: wx.App</p>
|
|
<div class="section">
|
|
<h2><a class="toc-backref" href="#id13" id="application-initialization" name="application-initialization">Application initialization</a></h2>
|
|
<p>The OnInit method defined for a class derived from wx.App will usually
|
|
create a top window as a bare minimum.</p>
|
|
<p>OnInit must return a boolean value to indicate whether processing
|
|
should continue (True) or not (False). You call App.SetTopWindow to
|
|
let wxPython know about the top window.</p>
|
|
<p>An application closes by destroying all windows. Because all frames
|
|
must be destroyed for the application to exit, it is advisable to use
|
|
parent frames wherever possible when creating new frames, so that
|
|
deleting the top level frame will automatically delete child frames.
|
|
The alternative is to explicitly delete child frames in the top-level
|
|
frame's CloseEvent handler.</p>
|
|
<p>In emergencies the wx.Exit() function can be called to kill the
|
|
application, however, normally the application shuts down
|
|
automatically, see below.</p>
|
|
<p>An example of defining an application follows:</p>
|
|
<pre class="literal-block">
|
|
import wx
|
|
|
|
from frame import Frame
|
|
|
|
class App(wx.App):
|
|
"""Application class."""
|
|
|
|
def OnInit(self):
|
|
self.frame = Frame()
|
|
self.frame.Show()
|
|
self.SetTopWindow(self.frame)
|
|
return True
|
|
|
|
def main():
|
|
app = App()
|
|
app.MainLoop()
|
|
|
|
if __name__ == '__main__':
|
|
main()
|
|
</pre>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a class="toc-backref" href="#id14" id="application-shutdown" name="application-shutdown">Application shutdown</a></h2>
|
|
<p>The application normally shuts down when the last of its top level
|
|
windows is closed. This is normally the expected behaviour and means
|
|
that it is enough to call Close() in response to the "Exit" menu
|
|
command if your program has a single top level window. If this
|
|
behaviour is not desirable, App.SetExitOnFrameDelete can be called to
|
|
change it. Note that such logic doesn't apply for the windows shown
|
|
before the program enters the main loop: in other words, you can
|
|
safely show a dialog from App.OnInit and not be afraid that your
|
|
application terminates when this dialog -- which is the last top level
|
|
window for the moment -- is closed.</p>
|
|
<p>Another aspect of the application shutdown is the OnExit which is
|
|
called when the application exits but before wxPython cleans up its
|
|
internal structures. You should delete all wxPython objects that you
|
|
created by the time OnExit finishes.</p>
|
|
<p>For example, this code may crash:</p>
|
|
<p>[Need examples of objects needing cleanup to keep app from crashing.]</p>
|
|
</div>
|
|
</div>
|
|
<div class="section">
|
|
<h1><a class="toc-backref" href="#id15" id="sizer-overview" name="sizer-overview">Sizer overview</a></h1>
|
|
<p>Classes: wx.Sizer, wx.GridSizer, wx.FlexGridSizer, wx.BoxSizer,
|
|
wx.StaticBoxSizer, wx.NotebookSizer, wx.CreateButtonSizer</p>
|
|
<table border="1" class="docutils">
|
|
<colgroup>
|
|
<col width="21%" />
|
|
<col width="79%" />
|
|
</colgroup>
|
|
<tbody valign="top">
|
|
<tr><td>Sizer</td>
|
|
<td>Abstract base class.</td>
|
|
</tr>
|
|
<tr><td>GridSizer</td>
|
|
<td>A sizer for laying out windows in a grid with all
|
|
fields having the same size.</td>
|
|
</tr>
|
|
<tr><td>FlexGridSizer</td>
|
|
<td>A sizer for laying out windows in a flexible grid.</td>
|
|
</tr>
|
|
<tr><td>BoxSizer</td>
|
|
<td>A sizer for laying out windows in a row or column.</td>
|
|
</tr>
|
|
<tr><td>StaticBoxSizer</td>
|
|
<td>Same as BoxSizer, but with a surrounding static box.</td>
|
|
</tr>
|
|
<tr><td>NotebookSizer</td>
|
|
<td>Sizer to use with the Notebook control.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p>Sizers, as represented by the wx.Sizer class and its descendants in
|
|
the wxPython class hierarchy, have become the method of choice to
|
|
define the layout of controls in dialogs in wxPython because of their
|
|
ability to create visually appealing dialogs independent of the
|
|
platform, taking into account the differences in size and style of the
|
|
individual controls. Editors such as wxDesigner, wxrcedit, XRCed and
|
|
wxWorkshop create dialogs based exclusively on sizers, practically
|
|
forcing the user to create platform independent layouts without
|
|
compromises.</p>
|
|
<div class="section">
|
|
<h2><a class="toc-backref" href="#id16" id="the-idea-behind-sizers" name="the-idea-behind-sizers">The idea behind sizers</a></h2>
|
|
<p>The layout algorithm used by sizers in wxPython is closely related to
|
|
layout systems in other GUI toolkits, such as Java's AWT, the GTK
|
|
toolkit or the Qt toolkit. It is based upon the idea of individual
|
|
subwindows reporting their minimal required size and their ability to
|
|
get stretched if the size of the parent window has changed. This will
|
|
most often mean that the programmer does not set the start-up size of
|
|
a dialog, the dialog will rather be assigned a sizer and this sizer
|
|
will be queried about the recommended size. This sizer in turn will
|
|
query its children (which can be normal windows, empty space or other
|
|
sizers) so that a hierarchy of sizers can be constructed. Note that
|
|
wx.Sizer does not derive from wx.Window and thus does not interfere
|
|
with tab ordering and requires very few resources compared to a real
|
|
window on screen.</p>
|
|
<p>What makes sizers so well fitted for use in wxPython is the fact that
|
|
every control reports its own minimal size and the algorithm can
|
|
handle differences in font sizes or different window (dialog item)
|
|
sizes on different platforms without problems. For example, if the
|
|
standard font as well as the overall design of Linux/GTK widgets
|
|
requires more space than on Windows, the initial dialog size will
|
|
automatically be bigger on Linux/GTK than on Windows.</p>
|
|
<p>There are currently five different kinds of sizers available in
|
|
wxPython. Each represents either a certain way to lay out dialog items
|
|
in a dialog or it fulfils a special task such as wrapping a static box
|
|
around a dialog item (or another sizer). These sizers will be
|
|
discussed one by one in the text below.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a class="toc-backref" href="#id17" id="common-features" name="common-features">Common features</a></h2>
|
|
<p>All sizers are containers, that is, they are used to lay out one
|
|
dialog item (or several dialog items), which they contain. Such items
|
|
are sometimes referred to as the children of the sizer. Independent
|
|
of how the individual sizers lay out their children, all children have
|
|
certain features in common:</p>
|
|
<div class="section">
|
|
<h3><a class="toc-backref" href="#id18" id="a-minimal-size" name="a-minimal-size">A minimal size</a></h3>
|
|
<p>This minimal size is usually identical to the initial size of the
|
|
controls and may either be set explicitly in the size field of the
|
|
control constructor or may be calculated by wxPython, typically by
|
|
setting the height and/or the width of the item to -1. Note that only
|
|
some controls can calculate their size (such as a checkbox) whereas
|
|
others (such as a listbox) don't have any natural width or height and
|
|
thus require an explicit size. Some controls can calculate their
|
|
height, but not their width (e.g. a single line text control):</p>
|
|
<p>[Need graphics]</p>
|
|
</div>
|
|
<div class="section">
|
|
<h3><a class="toc-backref" href="#id19" id="a-border" name="a-border">A border</a></h3>
|
|
<p>The border is just empty space and is used to separate dialog items in
|
|
a dialog. This border can either be all around, or at any combination
|
|
of sides such as only above and below the control. The thickness of
|
|
this border must be set explicitly, typically 5 points. The following
|
|
samples show dialogs with only one dialog item (a button) and a border
|
|
of 0, 5, and 10 pixels around the button:</p>
|
|
<p>[Need graphics]</p>
|
|
</div>
|
|
<div class="section">
|
|
<h3><a class="toc-backref" href="#id20" id="an-alignment" name="an-alignment">An alignment</a></h3>
|
|
<p>Often, a dialog item is given more space than its minimal size plus
|
|
its border. Depending on what flags are used for the respective dialog
|
|
item, the dialog item can be made to fill out the available space
|
|
entirely, i.e. it will grow to a size larger than the minimal size, or
|
|
it will be moved to either the centre of the available space or to
|
|
either side of the space. The following sample shows a listbox and
|
|
three buttons in a horizontal box sizer; one button is centred, one is
|
|
aligned at the top, one is aligned at the bottom:</p>
|
|
<p>[Need graphics]</p>
|
|
</div>
|
|
<div class="section">
|
|
<h3><a class="toc-backref" href="#id21" id="a-stretch-factor" name="a-stretch-factor">A stretch factor</a></h3>
|
|
<p>If a sizer contains more than one child and it is offered more space
|
|
than its children and their borders need, the question arises how to
|
|
distribute the surplus space among the children. For this purpose, a
|
|
stretch factor may be assigned to each child, where the default value
|
|
of 0 indicates that the child will not get more space than its
|
|
requested minimum size. A value of more than zero is interpreted in
|
|
relation to the sum of all stretch factors in the children of the
|
|
respective sizer, i.e. if two children get a stretch factor of 1, they
|
|
will get half the extra space each independent of whether one control
|
|
has a minimal sizer inferior to the other or not. The following
|
|
sample shows a dialog with three buttons, the first one has a stretch
|
|
factor of 1 and thus gets stretched, whereas the other two buttons
|
|
have a stretch factor of zero and keep their initial width:</p>
|
|
<p>[Need graphics]</p>
|
|
<p>Within wxDesigner, this stretch factor gets set from the Option menu.</p>
|
|
</div>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a class="toc-backref" href="#id22" id="boxsizer" name="boxsizer">BoxSizer</a></h2>
|
|
<p>BoxSizer can lay out its children either vertically or horizontally,
|
|
depending on what flag is being used in its constructor. When using a
|
|
vertical sizer, each child can be centered, aligned to the right or
|
|
aligned to the left. Correspondingly, when using a horizontal sizer,
|
|
each child can be centered, aligned at the bottom or aligned at the
|
|
top. The stretch factor described in the last paragraph is used for
|
|
the main orientation, i.e. when using a horizontal box sizer, the
|
|
stretch factor determines how much the child can be stretched
|
|
horizontally. The following sample shows the same dialog as in the
|
|
last sample, only the box sizer is a vertical box sizer now:</p>
|
|
<p>[Need graphics]</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a class="toc-backref" href="#id23" id="staticboxsizer" name="staticboxsizer">StaticBoxSizer</a></h2>
|
|
<p>StaticBoxSixer is the same as a BoxSizer, but surrounded by a static
|
|
box. Here is a sample:</p>
|
|
<p>[Need graphics]</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a class="toc-backref" href="#id24" id="gridsizer" name="gridsizer">GridSizer</a></h2>
|
|
<p>GridSizer is a two-dimensional sizer. All children are given the same
|
|
size, which is the minimal size required by the biggest child, in this
|
|
case the text control in the left bottom border. Either the number of
|
|
columns or the number or rows is fixed and the grid sizer will grow in
|
|
the respectively other orientation if new children are added:</p>
|
|
<p>[Need graphics]</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a class="toc-backref" href="#id25" id="flexgridsizer" name="flexgridsizer">FlexGridSizer</a></h2>
|
|
<p>Another two-dimensional sizer derived from GridSizer. The width of
|
|
each column and the height of each row are calculated individually
|
|
according the minimal requirements from the respectively biggest
|
|
child. Additionally, columns and rows can be declared to be
|
|
stretchable if the sizer is assigned a size different from that which
|
|
it requested. The following sample shows the same dialog as the one
|
|
above, but using a flex grid sizer:</p>
|
|
<p>[Need graphics]</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a class="toc-backref" href="#id26" id="notebooksizer" name="notebooksizer">NotebookSizer</a></h2>
|
|
<p>NotebookSizer can be used with notebooks. It calculates the size of
|
|
each notebook page and sets the size of the notebook to the size of
|
|
the biggest page plus some extra space required for the notebook tabs
|
|
and decorations.</p>
|
|
<p>[Need graphics]</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a class="toc-backref" href="#id27" id="programming-with-boxsizer" name="programming-with-boxsizer">Programming with BoxSizer</a></h2>
|
|
<p>The basic idea behind a BoxSizer is that windows will most often be
|
|
laid out in rather simple basic geometry, typically in a row or a
|
|
column or several hierarchies of either.</p>
|
|
<p>As an example, we will construct a dialog that will contain a text
|
|
field at the top and two buttons at the bottom. This can be seen as a
|
|
top-hierarchy column with the text at the top and buttons at the
|
|
bottom and a low-hierarchy row with an OK button to the left and a
|
|
Cancel button to the right. In many cases (particularly dialogs under
|
|
Unix and normal frames) the main window will be resizable by the user
|
|
and this change of size will have to get propagated to its children.
|
|
In our case, we want the text area to grow with the dialog, whereas
|
|
the button shall have a fixed size. In addition, there will be a thin
|
|
border around all controls to make the dialog look nice and - to make
|
|
matter worse - the buttons shall be centred as the width of the dialog
|
|
changes.</p>
|
|
<p>It is the unique feature of a box sizer, that it can grow in both
|
|
directions (height and width) but can distribute its growth in the
|
|
main direction (horizontal for a row) unevenly among its children. In
|
|
our example case, the vertical sizer is supposed to propagate all its
|
|
height changes to only the text area, not to the button area. This is
|
|
determined by the proportion parameter when adding a window (or
|
|
another sizer) to a sizer. It is interpreted as a weight factor,
|
|
i.e. it can be zero, indicating that the window may not be resized at
|
|
all, or above zero. If several windows have a value above zero, the
|
|
value is interpreted relative to the sum of all weight factors of the
|
|
sizer, so when adding two windows with a value of 1, they will both
|
|
get resized equally much and each half as much as the sizer owning
|
|
them.</p>
|
|
<p>Then what do we do when a column sizer changes its width? This
|
|
behaviour is controlled by flags (the second parameter of the Add()
|
|
function): zero or no flag indicates that the window will preserve it
|
|
is original size, wx.GROW flag (same as wx.EXPAND) forces the window
|
|
to grow with the sizer, and wx.SHAPED flag tells the window to change
|
|
it is size proportionally, preserving original aspect ratio. When
|
|
wx.GROW flag is not used, the item can be aligned within available
|
|
space. wx.ALIGN_LEFT, wx.ALIGN_TOP, wx.ALIGN_RIGHT, wx.ALIGN_BOTTOM,
|
|
wx.ALIGN_CENTER_HORIZONTAL and wx.ALIGN_CENTER_VERTICAL do what they
|
|
say. wx.ALIGN_CENTRE (same as wx.ALIGN_CENTER) is defined as
|
|
(<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
|
|
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>
|
|
<p>As mentioned above, any window belonging to a sizer may have border,
|
|
and it can be specified which of the four sides may have this border,
|
|
using the wx.TOP, wx.LEFT, wx.RIGHT and wx.BOTTOM constants or wx.ALL
|
|
for all directions (and you may also use wx.NORTH, wx.WEST etc
|
|
instead). These flags can be used in combination with the alignment
|
|
flags above as the second parameter of the Add() method using the
|
|
binary or operator (<tt class="docutils literal"><span class="pre">|</span></tt>). The sizer of the border also must be made
|
|
known, and it is the third parameter in the Add() method. This means,
|
|
that the entire behaviour of a sizer and its children can be
|
|
controlled by the three parameters of the Add() method.</p>
|
|
<p>[Show code and graphic here.]</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a class="toc-backref" href="#id28" id="programming-with-gridsizer" name="programming-with-gridsizer">Programming with GridSizer</a></h2>
|
|
<p>GridSizer is a sizer which lays out its children in a two-dimensional
|
|
table with all table fields having the same size, i.e. the width of
|
|
each field is the width of the widest child, the height of each field
|
|
is the height of the tallest child.</p>
|
|
<p>[Show code and graphic here.]</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a class="toc-backref" href="#id29" id="programming-with-flexgridsizer" name="programming-with-flexgridsizer">Programming with FlexGridSizer</a></h2>
|
|
<p>FlexGridSizer is a sizer which lays out its children in a
|
|
two-dimensional table with all table fields in one row having the same
|
|
height and all fields in one column having the same width, but all
|
|
rows or all columns are not necessarily the same height or width as in
|
|
the GridSizer.</p>
|
|
<p>[Show code and graphic here.]</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a class="toc-backref" href="#id30" id="programming-with-notebooksizer" name="programming-with-notebooksizer">Programming with NotebookSizer</a></h2>
|
|
<p>NotebookSizer is a specialized sizer to make sizers work in connection
|
|
with using notebooks. This sizer is different from any other sizer as
|
|
you must not add any children to it - instead, it queries the notebook
|
|
class itself. The only thing this sizer does is to determine the size
|
|
of the biggest page of the notebook and report an adjusted minimal
|
|
size to a more toplevel sizer.</p>
|
|
<p>In order to query the size of notebook page, this page needs to have
|
|
its own sizer, otherwise the NotebookSizer will ignore it. Notebook
|
|
pages get their sizer by assigning one to them using SetSizer() and
|
|
setting the auto-layout option to True using SetAutoLayout(). Here is
|
|
one example showing how to add a notebook page that the notebook sizer
|
|
is aware of:</p>
|
|
<p>[Show code and graphic here.]</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a class="toc-backref" href="#id31" id="programming-with-staticboxsizer" name="programming-with-staticboxsizer">Programming with StaticBoxSizer</a></h2>
|
|
<p>StaticBoxSizer is a sizer derived from BoxSizer but adds a static box
|
|
around the sizer. Note that this static box has to be created
|
|
separately.</p>
|
|
<p>[Show code and graphic here.]</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a class="toc-backref" href="#id32" id="dialog-createbuttonsizer" name="dialog-createbuttonsizer">Dialog.CreateButtonSizer</a></h2>
|
|
<p>As a convenience, the Dialog class has a CreateButtonSizer(flags)
|
|
method that can be used to create a standard button sizer in which
|
|
standard buttons are displayed. The following flags can be passed to
|
|
this method:</p>
|
|
<table border="1" class="docutils">
|
|
<colgroup>
|
|
<col width="19%" />
|
|
<col width="81%" />
|
|
</colgroup>
|
|
<tbody valign="top">
|
|
<tr><td>wx.YES_NO</td>
|
|
<td>add Yes/No subpanel</td>
|
|
</tr>
|
|
<tr><td>wx.YES</td>
|
|
<td>return wx.ID_YES</td>
|
|
</tr>
|
|
<tr><td>wx.NO</td>
|
|
<td>return wx.ID_NO</td>
|
|
</tr>
|
|
<tr><td>wx.NO_DEFAULT</td>
|
|
<td>make the wx.NO button the default, otherwise wx.YES or
|
|
wx.OK button will be default</td>
|
|
</tr>
|
|
<tr><td>wx.OK</td>
|
|
<td>return wx.ID_OK</td>
|
|
</tr>
|
|
<tr><td>wx.CANCEL</td>
|
|
<td>return wx.ID_CANCEL</td>
|
|
</tr>
|
|
<tr><td>wx.HELP</td>
|
|
<td>return wx.ID_HELP</td>
|
|
</tr>
|
|
<tr><td>wx.FORWARD</td>
|
|
<td>return wx.ID_FORWARD</td>
|
|
</tr>
|
|
<tr><td>wx.BACKWARD</td>
|
|
<td>return wx.ID_BACKWARD</td>
|
|
</tr>
|
|
<tr><td>wx.SETUP</td>
|
|
<td>return wx.ID_SETUP</td>
|
|
</tr>
|
|
<tr><td>wx.MORE</td>
|
|
<td>return wx.ID_MORE</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
<div class="section">
|
|
<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>
|
|
<p>wxPython provides a set of powerful classes to work with dates and
|
|
times. Some of the supported features of the DateTime class are:</p>
|
|
<table border="1" class="docutils">
|
|
<colgroup>
|
|
<col width="18%" />
|
|
<col width="82%" />
|
|
</colgroup>
|
|
<tbody valign="top">
|
|
<tr><td>Wide range</td>
|
|
<td>The range of supported dates goes from about 4714 B.C. to
|
|
some 480 million years in the future.</td>
|
|
</tr>
|
|
<tr><td>Precision</td>
|
|
<td>Not using floating point calculations anywhere ensures that
|
|
the date calculations don't suffer from rounding
|
|
errors.</td>
|
|
</tr>
|
|
<tr><td>Many features</td>
|
|
<td>Not only all usual calculations with dates are
|
|
supported, but also more exotic week and year day
|
|
calculations, work day testing, standard astronomical
|
|
functions, conversion to and from strings in either
|
|
strict or free format.</td>
|
|
</tr>
|
|
<tr><td>Efficiency</td>
|
|
<td>Objects of DateTime are small (8 bytes) and working
|
|
with them is fast</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<div class="section">
|
|
<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>
|
|
<p>There are 3 main classes: except DateTime itself which represents an
|
|
absolute moment in time, there are also two classes - TimeSpan and
|
|
DateSpan which represent the intervals of time.</p>
|
|
<p>There are also helper classes which are used together with DateTime:
|
|
DateTimeHolidayAuthority which is used to determine whether a given
|
|
date is a holiday or not and DateTimeWorkDays which is a derivation of
|
|
this class for which (only) Saturdays and Sundays are the holidays.
|
|
See more about these classes in the discussion of the holidays.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a class="toc-backref" href="#id35" id="datetime-characteristics" name="datetime-characteristics">DateTime characteristics</a></h2>
|
|
<p>DateTime stores the time as a signed number of milliseconds since the
|
|
Epoch which is fixed, by convention, to Jan 1, 1970 - however this is
|
|
not visible to the class users (in particular, dates prior to the
|
|
Epoch are handled just as well (or as bad) as the dates after it).
|
|
But it does mean that the best resolution which can be achieved with
|
|
this class is 1 millisecond.</p>
|
|
<p>The size of DateTime object is 8 bytes because it is represented as a
|
|
64 bit integer. The resulting range of supported dates is thus
|
|
approximatively 580 million years, but due to the current limitations
|
|
in the Gregorian calendar support, only dates from Nov 24, 4714BC are
|
|
supported (this is subject to change if there is sufficient interest
|
|
in doing it).</p>
|
|
<p>Finally, the internal representation is time zone independent (always
|
|
in GMT) and the time zones only come into play when a date is broken
|
|
into year/month/day components. See more about timezones below.</p>
|
|
<p>Currently, the only supported calendar is Gregorian one (which is used
|
|
even for the dates prior to the historic introduction of this calendar
|
|
which was first done on Oct 15, 1582 but is, generally speaking,
|
|
country, and even region, dependent). Future versions will probably
|
|
have Julian calendar support as well and support for other calendars
|
|
(Maya, Hebrew, Chinese...) is not ruled out.</p>
|
|
</div>
|
|
<div class="section">
|
|
<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>
|
|
<p>While there is only one logical way to represent an absolute moment in
|
|
the time (and hence only one DateTime class), there are at least two
|
|
methods to describe a time interval.</p>
|
|
<p>First, there is the direct and self-explaining way implemented by
|
|
TimeSpan: it is just a difference in milliseconds between two moments
|
|
in time. Adding or subtracting such an interval to DateTime is always
|
|
well-defined and is a fast operation.</p>
|
|
<p>But in daily life other, calendar-dependent time interval
|
|
specifications are used. For example, 'one month later' is commonly
|
|
used. However, it is clear that this is not the same as TimeSpan of
|
|
60*60*24*31 seconds because 'one month later' Feb 15 is Mar 15 and not
|
|
Mar 17 or Mar 16 (depending on whether the year is leap or not).</p>
|
|
<p>This is why there is another class for representing such intervals
|
|
called DateSpan. It handles these sort of operations in the most
|
|
natural way possible, but note that manipulating with intervals of
|
|
this kind is not always well-defined. Consider, for example, Jan 31 +
|
|
'1 month': this will give Feb 28 (or 29), i.e. the last day of
|
|
February and not the non-existent Feb 31. Of course, this is what is
|
|
usually wanted, but you still might be surprised to notice that now
|
|
subtracting back the same interval from Feb 28 will result in Jan 28
|
|
and not Jan 31 we started with!</p>
|
|
<p>So, unless you plan to implement some kind of natural language parsing
|
|
in the program, you should probably use TimeSpan instead of DateSpan
|
|
(which is also more efficient). However, DateSpan may be very useful
|
|
in situations when you do need to understand what 'in a month' means
|
|
(of course, it is just DateTime.Now() + DateSpan.Month()).</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a class="toc-backref" href="#id37" id="date-arithmetics" name="date-arithmetics">Date arithmetics</a></h2>
|
|
<p>Many different operations may be performed with the dates, however not
|
|
all of them make sense. For example, multiplying a date by a number
|
|
is an invalid operation, even though multiplying either of the time
|
|
span classes by a number is perfectly valid.</p>
|
|
<p>Here is what can be done:</p>
|
|
<table border="1" class="docutils">
|
|
<colgroup>
|
|
<col width="19%" />
|
|
<col width="81%" />
|
|
</colgroup>
|
|
<tbody valign="top">
|
|
<tr><td>Addition</td>
|
|
<td>a TimeSpan or DateSpan can be added to DateTime resulting in
|
|
a new DateTime object and also 2 objects of the same
|
|
span class can be added together giving another object
|
|
of the same class.</td>
|
|
</tr>
|
|
<tr><td>Subtraction</td>
|
|
<td>the same types of operations as above are allowed and,
|
|
additionally, a difference between two DateTime
|
|
objects can be taken and this will yield TimeSpan.</td>
|
|
</tr>
|
|
<tr><td>Multiplication</td>
|
|
<td>a TimeSpan or DateSpan object can be multiplied by an
|
|
integer number resulting in an object of the same
|
|
type.</td>
|
|
</tr>
|
|
<tr><td>Unary minus</td>
|
|
<td>a TimeSpan or DateSpan object may finally be negated
|
|
giving an interval of the same magnitude but of
|
|
opposite time direction.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a class="toc-backref" href="#id38" id="time-zone-considerations" name="time-zone-considerations">Time zone considerations</a></h2>
|
|
<p>Although the time is always stored internally in GMT, you will usually
|
|
work in the local time zone. Because of this, all DateTime
|
|
constructors and setters which take the broken down date assume that
|
|
these values are for the local time zone. Thus, DateTime(1,
|
|
DateTime.Jan, 1970) will not correspond to the DateTime Epoch unless
|
|
you happen to live in the UK.</p>
|
|
<p>All methods returning the date components (year, month, day, hour,
|
|
minute, second...) will also return the correct values for the local
|
|
time zone by default. So, generally, doing the natural things will
|
|
lead to natural and correct results.</p>
|
|
<p>If you only want to do this, you may safely skip the rest of this
|
|
section. However, if you want to work with different time zones, you
|
|
should read it to the end.</p>
|
|
<p>In this (rare) case, you are still limited to the local time zone when
|
|
constructing DateTime objects, i.e. there is no way to construct a
|
|
DateTime corresponding to the given date in, say, Pacific Standard
|
|
Time. To do it, you will need to call ToTimezone or MakeTimezone
|
|
methods to adjust the date for the target time zone. There are also
|
|
special versions of these functions ToGMT and MakeGMT for the most
|
|
common case - when the date should be constructed in GMT.</p>
|
|
<p>You also can just retrieve the value for some time zone without
|
|
converting the object to it first. For this you may pass TimeZone
|
|
argument to any of the methods which are affected by the time zone
|
|
(all methods getting date components and the date formatting ones, for
|
|
example). In particular, the Format() family of methods accepts a
|
|
TimeZone parameter and this allows to simply print time in any time
|
|
zone.</p>
|
|
<p>To see how to do it, the last issue to address is how to construct a
|
|
TimeZone object which must be passed to all these methods. First of
|
|
all, you may construct it manually by specifying the time zone offset
|
|
in seconds from GMT, but usually you will just use one of the symbolic
|
|
time zone names and let the conversion constructor do the
|
|
job. I.e. you would just write</p>
|
|
<p>wxDateTime dt(...whatever...);
|
|
printf("The time is %s in local time zone", dt.FormatTime().c_str());
|
|
printf("The time is %s in GMT", dt.FormatTime(wxDateTime::GMT).c_str());</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a class="toc-backref" href="#id39" id="daylight-saving-time-dst" name="daylight-saving-time-dst">Daylight saving time (DST)</a></h2>
|
|
<p>DST (a.k.a. 'summer time') handling is always a delicate task which is
|
|
better left to the operating system which is supposed to be configured
|
|
by the administrator to behave correctly. Unfortunately, when doing
|
|
calculations with date outside of the range supported by the standard
|
|
library, we are forced to deal with these issues ourselves.</p>
|
|
<p>Several functions are provided to calculate the beginning and end of
|
|
DST in the given year and to determine whether it is in effect at the
|
|
given moment or not, but they should not be considered as absolutely
|
|
correct because, first of all, they only work more or less correctly
|
|
for only a handful of countries (any information about other ones
|
|
appreciated!) and even for them the rules may perfectly well change in
|
|
the future.</p>
|
|
<p>The time zone handling methods use these functions too, so they are
|
|
subject to the same limitations.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a class="toc-backref" href="#id40" id="datetime-and-holidays" name="datetime-and-holidays">DateTime and Holidays</a></h2>
|
|
<p>[TODO]</p>
|
|
</div>
|
|
</div>
|
|
<div class="section">
|
|
<h1><a class="toc-backref" href="#id41" id="classes-by-category" name="classes-by-category">Classes by category</a></h1>
|
|
<p>Not done yet.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h1><a class="toc-backref" href="#id42" id="id-constants" name="id-constants">ID constants</a></h1>
|
|
<p>wxPython provides the following predefined ID constants:</p>
|
|
<p>ID_ABORT
|
|
ID_ABOUT
|
|
ID_ANY
|
|
ID_APPLY
|
|
ID_BACKWARD
|
|
ID_CANCEL
|
|
ID_CLEAR
|
|
ID_CLOSE
|
|
ID_CLOSE_ALL
|
|
ID_CONTEXT_HELP
|
|
ID_COPY
|
|
ID_CUT
|
|
ID_DEFAULT
|
|
ID_DUPLICATE
|
|
ID_EXIT
|
|
ID_FILE1
|
|
ID_FILE2
|
|
ID_FILE3
|
|
ID_FILE4
|
|
ID_FILE5
|
|
ID_FILE6
|
|
ID_FILE7
|
|
ID_FILE8
|
|
ID_FILE9
|
|
ID_FILTERLISTCTRL
|
|
ID_FIND
|
|
ID_FORWARD
|
|
ID_HELP
|
|
ID_HELP_COMMANDS
|
|
ID_HELP_CONTENTS
|
|
ID_HELP_CONTEXT
|
|
ID_HELP_PROCEDURES
|
|
ID_IGNORE
|
|
ID_MORE
|
|
ID_NEW
|
|
ID_NO
|
|
ID_NOTOALL
|
|
ID_OK
|
|
ID_OPEN
|
|
ID_PASTE
|
|
ID_PREVIEW
|
|
ID_PRINT
|
|
ID_PRINT_SETUP
|
|
ID_REDO
|
|
ID_RESET
|
|
ID_RETRY
|
|
ID_REVERT
|
|
ID_SAVE
|
|
ID_SAVEAS
|
|
ID_SELECTALL
|
|
ID_SEPARATOR
|
|
ID_SETUP
|
|
ID_STATIC
|
|
ID_TREECTRL
|
|
ID_UNDO
|
|
ID_YES
|
|
ID_YESTOALL</p>
|
|
</div>
|
|
<div class="section">
|
|
<h1><a class="toc-backref" href="#id43" id="source-document" name="source-document">Source document</a></h1>
|
|
<p>The source document is named wxPythonManual.txt and can be found by
|
|
clicking the link at the bottom of this page (assuming you are viewing
|
|
the html file). It is written using a fantastic formatting convention
|
|
called reStructuredText. The wxPythonManual.html file is created
|
|
using the Docutils utilities, which can turn reStructuredText
|
|
documents into html, xml, pdf, and even OpenOffice files.</p>
|
|
</div>
|
|
<div class="section">
|
|
<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>
|
|
<p>Some items in the source text file look like this:</p>
|
|
<pre class="literal-block">
|
|
.. This is text from the wxWidgets documentation that needs to be
|
|
translated into something appropriate for the wxPython version.
|
|
The two dots followed by uniformly indented text turns this
|
|
paragraph into a reStructuredText comment, so it doesn't appear
|
|
in any output file, such as the html file.
|
|
</pre>
|
|
<p>They have been commented out and are awaiting editorial review and a
|
|
rewrite so that they make sense in the context of wxPython. Feel free
|
|
to send me suggestions for rewording these, or any other parts of this
|
|
document that you think need improving. I will be eternally grateful
|
|
to you and will show my gratitude by adding your name to the list of
|
|
contributors. (Contributors who also send me gifts of coffee,
|
|
chocolate, or currency will have their names listed in bold.)</p>
|
|
</div>
|
|
<div class="section">
|
|
<h1><a class="toc-backref" href="#id45" id="contributors" name="contributors">Contributors</a></h1>
|
|
<p>Individuals who contributed to this documentation (in order by last
|
|
name):</p>
|
|
<ul class="simple">
|
|
<li>Robin Dunn</li>
|
|
<li>Patrick K. O'Brien</li>
|
|
<li>Robert Roebling</li>
|
|
<li>Julian Smart</li>
|
|
<li>Vadim Zeitlin</li>
|
|
</ul>
|
|
</div>
|
|
<div class="section">
|
|
<h1><a class="toc-backref" href="#id46" id="license" name="license">License</a></h1>
|
|
<p>This document began as a translation of the wxWidgets documentation.
|
|
As such, it adheres to the same license, which is provided here:</p>
|
|
<pre class="literal-block">
|
|
wxWindows Free Documentation Licence, Version 3
|
|
===============================================
|
|
|
|
Copyright (c) 1998 Julian Smart, Robert Roebling et al
|
|
|
|
Everyone is permitted to copy and distribute verbatim copies
|
|
of this licence document, but changing it is not allowed.
|
|
|
|
WXWINDOWS FREE DOCUMENTATION LICENCE
|
|
TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
|
|
|
|
1. Permission is granted to make and distribute verbatim copies of this
|
|
manual or piece of documentation provided any copyright notice and this
|
|
permission notice are preserved on all copies.
|
|
|
|
2. Permission is granted to process this file or document through a
|
|
document processing system and, at your option and the option of any third
|
|
party, print the results, provided a printed document carries a copying
|
|
permission notice identical to this one.
|
|
|
|
3. Permission is granted to copy and distribute modified versions of this
|
|
manual or piece of documentation under the conditions for verbatim
|
|
copying, provided also that any sections describing licensing conditions
|
|
for this manual, such as, in particular, the GNU General Public Licence,
|
|
the GNU Library General Public Licence, and any wxWindows Licence are
|
|
included exactly as in the original, and provided that the entire
|
|
resulting derived work is distributed under the terms of a permission
|
|
notice identical to this one.
|
|
|
|
4. Permission is granted to copy and distribute translations of this
|
|
manual or piece of documentation into another language, under the above
|
|
conditions for modified versions, except that sections related to
|
|
licensing, including this paragraph, may also be included in translations
|
|
approved by the copyright holders of the respective licence documents in
|
|
addition to the original English.
|
|
|
|
WARRANTY DISCLAIMER
|
|
|
|
5. BECAUSE THIS MANUAL OR PIECE OF DOCUMENTATION IS LICENSED FREE OF CHARGE,
|
|
THERE IS NO WARRANTY FOR IT, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
|
|
EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER
|
|
PARTIES PROVIDE THIS MANUAL OR PIECE OF DOCUMENTATION "AS IS" WITHOUT
|
|
WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT
|
|
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
|
|
PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF
|
|
THE MANUAL OR PIECE OF DOCUMENTATION IS WITH YOU. SHOULD THE MANUAL OR
|
|
PIECE OF DOCUMENTATION PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
|
|
NECESSARY SERVICING, REPAIR OR CORRECTION.
|
|
|
|
6. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL
|
|
ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
|
|
REDISTRIBUTE THE MANUAL OR PIECE OF DOCUMENTATION AS PERMITTED ABOVE, BE
|
|
LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
|
|
CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
|
|
MANUAL OR PIECE OF DOCUMENTATION (INCLUDING BUT NOT LIMITED TO LOSS OF
|
|
DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
|
|
PARTIES OR A FAILURE OF A PROGRAM BASED ON THE MANUAL OR PIECE OF
|
|
DOCUMENTATION TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR
|
|
OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
|
|
|
|
|
|
</pre>
|
|
</div>
|
|
</div>
|
|
</body>
|
|
</html>
|