-
Example Programs Using wxPython
-
A survival guide for the post-wx-prefixed world.
-
-
-
-
-| Author: |
-Patrick K. O'Brien |
|---|
-| Contact: |
-pobrien@orbtech.com |
|---|
-| Date: |
-2003-03-21 |
|---|
-| Revision: |
-1.1 |
|---|
-
-
-
-
-
-
If something hits you on the head, don't run around screaming that the
-sky is falling. Instead, take a close look and see if it wasn't a
-"wx" prefix that hit you. Apparently, they're dropping off wxPython
-class names like flies dropping dead in the scorching heat of a
-summer's day.
-
Yes, the world is changing, and even our little wxPython world must
-change with it. Then again, I'm not fond of pesky summertime flies,
-and I'm not too upset that the "wx" prefixes are going to bite the
-dust. I think it's for the best. But, being the kind, considerate
-person that I am, I decided to write this guide to make the wx
-namespace transition easier for everyone, even Chicken Little.
-
-
Rather than simply tell you that everything will be okay, I
-decided to show you that everything will be okay. To do that,
-I've created a bunch of example programs using the new wx package. I
-hope you like them.
-
-
-
-
It doesn't get much simpler than this. Every wxPython program needs
-an application and a frame. To encourage good coding habits, I've
-split them into separate modules. They don't do much, but they're a
-good starting point.
-
I include a simple App class in the frame module because the PyCrust
-"wrapper" utility (wrap.py) only works with modules that contain
-an application class. So including a simple one in each of your frame
-modules allows you to use the PyCrust runtime wrapper and debug your
-frames independent of your full application.
-
Here is the module (frame.py) that defines the frame class:
-
-#!/usr/bin/env python
-
-"""Basic frame class, with App for testing."""
-
-__author__ = "Patrick K. O'Brien <pobrien@orbtech.com>"
-__cvsid__ = "$Id$"
-__revision__ = "$Revision$"[11:-2]
-
-import wx
-
-class Frame(wx.Frame):
- """Frame class."""
-
- def __init__(self, parent=None, id=-1, title='Title',
- pos=wx.DefaultPosition, size=(400, 200)):
- """Create a Frame instance."""
- wx.Frame.__init__(self, parent, id, title, pos, size)
-
-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()
-
-
-
And here is the module (app.py) that defines the application class
-and imports the frame from frame.py:
-
-#!/usr/bin/env python
-
-"""Basic application class."""
-
-__author__ = "Patrick K. O'Brien <pobrien@orbtech.com>"
-__cvsid__ = "$Id$"
-__revision__ = "$Revision$"[11:-2]
-
-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()
-
-
-
-
-
-
This program displays an image file (wxPython.jpg) inside a frame
-sized to match the graphic.
-
-
-
-
Here is the source code for hello.py:
-
-#!/usr/bin/env python
-
-"""Hello, wxPython! program."""
-
-__author__ = "Patrick K. O'Brien <pobrien@orbtech.com>"
-__cvsid__ = "$Id$"
-__revision__ = "$Revision$"[11:-2]
-
-import wx
-
-class Frame(wx.Frame):
- """Frame class that displays an image."""
-
- def __init__(self, image, parent=None, id=-1,
- pos=wx.DefaultPosition, title='Hello, wxPython!'):
- """Create a Frame instance and display image."""
- temp = image.ConvertToBitmap()
- size = temp.GetWidth(), temp.GetHeight()
- wx.Frame.__init__(self, parent, id, title, pos, size)
- self.bmp = wx.StaticBitmap(parent=self, id=-1, bitmap=temp)
-
-class App(wx.App):
- """Application class."""
-
- def OnInit(self):
- wx.InitAllImageHandlers()
- image = wx.Image('wxPython.jpg', wx.BITMAP_TYPE_JPEG)
- self.frame = Frame(image)
- self.frame.Show()
- self.SetTopWindow(self.frame)
- return True
-
-def main():
- app = App()
- app.MainLoop()
-
-if __name__ == '__main__':
- main()
-
-
-
-
-
The wxPython wx Package
-
How to survive the new wx namespace changes.
-
-
-
-
-| Author: |
-Patrick K. O'Brien |
|---|
-| Contact: |
-pobrien@orbtech.com |
|---|
-| Date: |
-2003-03-21 |
|---|
-| Revision: |
-1.1 |
|---|
-
-
-
-
-
-
Big things sometimes come in small packages. This is certainly true
-of the new wx package, which is being introduced as a transition to
-allow the "wx" prefix to be dropped from the names of all wxPython
-classes, functions, and constants.
-
-
-
-
This change is being made for a couple of reasons. The first reason
-is to discourage the use of import *, which is a dangerous
-technique that can create name conflicts and bloated namespaces.
-
The second reason is to remove what some perceive to be a "wart." For
-example, the following code is rather ugly in that the "wx" prefix on
-the wxFrame class name is no longer useful when you're using the wx
-module prefix:
-
-from wxPython import wx
-
-class Frame(wx.wxFrame)
-
-
The new wx package allows you to write code like this, instead:
-
-import wx
-
-class Frame(wx.Frame)
-
-
The third reason is that the wxWindows project intends to do the same
-thing (implement a new wx namespace and drop the "wx" prefix) and we
-want wxPython to lead the way.
-
-
-
-
As a way of getting to this new syntax as quickly as possible, the
-code in this new wx package was created. What it does is alter the
-existing wx namespace dynamically. By making the changes on-the-fly
-at runtime, we can try out the new syntax before any permanent changes
-are made to the underlying class library. The downside of making
-these changes at runtime is that there is a slight delay when you
-import wx; the upside is that you can start using the new syntax
-now.
-
-
-
-
No. Your existing code will continue to work and be supported for
-some time. It will be up to you to decide when to switch to the new
-syntax. But all new documentation and code examples will use the new
-syntax. So don't wait too long. You wouldn't want anyone calling you
-old-fashioned, would you?
-
-
-
-
It's pretty simple, and pretty clever. The wx directory contains an
-__init__.py file, making it a Python package. (In contrast, the
-old wxPython.wx module is a module, not a package.) When you import
-wx the code in the __init__.py file is executed, and that's
-where all the magic takes place. Let's take a look at the code inside
-the __init__.py file:
-
-"""wx package
-
-Provides a way to drop the wx prefix from wxPython objects."""
-
-__author__ = "Patrick K. O'Brien <pobrien@orbtech.com>"
-__cvsid__ = "$Id$"
-__revision__ = "$Revision$"[11:-2]
-
-from wxPython import wx
-
-import types
-
-d_new = globals()
-d_old = wx.__dict__
-
-for old, obj in d_old.iteritems():
- if type(obj) is types.ModuleType or old.startswith('_'):
- # Skip modules and private names.
- continue
- new = old
- if old.startswith('EVT_'):
- # Leave name unmodified; add to the new wx namespace.
- d_new[new] = obj
- elif old.startswith('wxEVT_'):
- # Leave name unmodified; add to the new wx namespace.
- d_new[new] = obj
- else:
- if old.startswith('wx'):
- # Remove the 'wx' prefix.
- new = old[2:]
- # Add to the new wx package namespace.
- d_new[new] = obj
-
-del d_new
-del d_old
-del new
-del obj
-del old
-del types
-
-del wx
-
-
-
Namespaces in Python are implemented as dictionaries. The dictionary
-used to create the wx package's namespace is accessible using the
-globals() function. The dictionary used to create the old
-wxPython.wx module's namespace is wx.__dict__. Once we have these
-two dictionaries, it's a simple matter of iterating through one,
-changing the names, adding the renamed object to the other dictionary,
-and cleaning up a few local variables and imported modules. Voila!
-
-
-
-
There's more to wxPython than just the wx namespace. And we've got
-those extra modules covered as well. For each of those modules (as
-well as the lib package) we've got matching modules in the new wx
-package. Let's take a look at a few of them.
-
Here is html.py:
-
-"""Provides a way to drop the wx prefix from wxPython objects."""
-
-__author__ = "Patrick K. O'Brien <pobrien@orbtech.com>"
-__cvsid__ = "$Id$"
-__revision__ = "$Revision$"[11:-2]
-
-import wx
-from wx import prefix
-
-from wxPython import html
-prefix.rename(d_new=globals(), d_old=html.__dict__)
-del html
-
-del prefix
-del wx
-
-
-
And here is lib/dialogs.py:
-
-"""Provides a way to drop the wx prefix from wxPython objects."""
-
-__author__ = "Patrick K. O'Brien <pobrien@orbtech.com>"
-__cvsid__ = "$Id$"
-__revision__ = "$Revision$"[11:-2]
-
-import wx
-from wx import prefix
-
-from wxPython.lib import dialogs
-prefix.rename(d_new=globals(), d_old=dialogs.__dict__)
-del dialogs
-
-del prefix
-del wx
-
-
-
As you can see, they both rely on the prefix.rename() function
-defined in prefix.py:
-
-"""Renaming utility.
-
-Provides a way to drop the wx prefix from wxPython objects."""
-
-__author__ = "Patrick K. O'Brien <pobrien@orbtech.com>"
-__cvsid__ = "$Id$"
-__revision__ = "$Revision$"[11:-2]
-
-import types
-
-def rename(d_new, d_old):
- for old, obj in d_old.iteritems():
- if type(obj) is types.ModuleType or old.startswith('_'):
- # Skip modules and private names.
- continue
-## mod = d_old['__name__']
-## if hasattr(obj, '__module__') and not obj.__module__.startswith(mod):
-## # Skip objects imported from other modules, except those
-## # related to the current module, such as stc_.
-## continue
- new = old
- if old.startswith('EVT_') or old.startswith('wxEVT_'):
- # Leave these names unmodified.
- pass
- elif old.startswith('wx'):
- new = old[2:]
- if new:
- d_new[new] = d_old[old]
-
-
-
Again, the technique is very similar to the one used by the wx
-package.
-
-
-
-
The wx package is created when you install wxPython. So you can start
-using it now. Examples are included in the wx/examples directory,
-which includes an examples.txt documentation file. Here is the source
-code for hello.py, a simple program that displays a wxPython
-graphic inside a frame:
-
-#!/usr/bin/env python
-
-"""Hello, wxPython! program."""
-
-__author__ = "Patrick K. O'Brien <pobrien@orbtech.com>"
-__cvsid__ = "$Id$"
-__revision__ = "$Revision$"[11:-2]
-
-import wx
-
-class Frame(wx.Frame):
- """Frame class that displays an image."""
-
- def __init__(self, image, parent=None, id=-1,
- pos=wx.DefaultPosition, title='Hello, wxPython!'):
- """Create a Frame instance and display image."""
- temp = image.ConvertToBitmap()
- size = temp.GetWidth(), temp.GetHeight()
- wx.Frame.__init__(self, parent, id, title, pos, size)
- self.bmp = wx.StaticBitmap(parent=self, id=-1, bitmap=temp)
-
-class App(wx.App):
- """Application class."""
-
- def OnInit(self):
- wx.InitAllImageHandlers()
- image = wx.Image('wxPython.jpg', wx.BITMAP_TYPE_JPEG)
- self.frame = Frame(image)
- self.frame.Show()
- self.SetTopWindow(self.frame)
- return True
-
-def main():
- app = App()
- app.MainLoop()
-
-if __name__ == '__main__':
- main()
-
-
-
Good luck. I hope you like the new wx package as much as I do.
-
Pat
-
-
-
The wxPython Reference
-
-
-
-
-
-| Author: |
-Patrick K. O'Brien |
|---|
-| Contact: |
-pobrien@orbtech.com |
|---|
-| Date: |
-2003-03-22 |
|---|
-| Revision: |
-1.2 |
|---|
-| License: | wxWindows Free Documentation Licence, Version 3 |
-
|---|
-
-
-
-
-
-
This is a guide to the wxPython GUI toolkit, written by a Python
-programmer for his fellow Python programmers. It began as a
-simple translation of the wxWindows documentation (which is written
-for C++ programmers), and evolved from there. And while there's
-nothing wrong with C++...
-
Okay, you got me there. I hate C++. That's why I use Python. If you
-like C++, go read the wxWindows 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.
-
-
-
-
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 wxWindows cross platform GUI library, which is written in C++.
-
Like Python and wxWindows, 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.
-
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.
-
Since the language is Python, wxPython programs are simple, easy to
-write and easy to understand.
-
-
-
-
To make use of wxPython, you currently need one of the following
-setups.
-
-
-
-- A 486 or higher PC running MS Windows.
-- At least ?? MB of disk space.
-
-
-
-
-
-- Almost any C++ compiler, including GNU C++ (EGCS 1.1.1 or above).
-- Almost any Unix workstation, and one of: GTK+ 1.2, GTK+ 2.0, Motif
-1.2 or higher, Lesstif.
-- At least ?? MB of disk space.
-
-
-
-
-
-- A PowerPC Mac running Mac OS X 10.x.
-- At least ?? MB of disk space.
-
-
-
-
-
-
wxWindows 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.
-
wxWindows 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.
-
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.
-
-
-
-
wxWindows 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:
-
-- low price
-- source availability
-- simplicity of programming
-- support for a wide range of compilers
-
-
Since wxWindows 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 wxWindows has.
-
As open source software, wxWindows has benefited from comments, ideas,
-bug fixes, enhancements and the sheer enthusiasm of users. This gives
-wxWindows 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.
-
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.
-
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. wxWindows helps to insulate the programmer from
-these winds of change. Although wxWindows 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
-wxWindows even if they are developing on only one platform.
-
It is impossible to sum up the functionality of wxWindows in a few
-paragraphs, but here are some of the benefits:
-
-- Low cost (free, in fact!)
-- You get the source.
-- Available on a variety of popular platforms.
-- Works with almost all popular C++ compilers and Python.
-- Over 50 example programs.
-- Over 1000 pages of printable and on-line documentation.
-- Includes Tex2RTF, to allow you to produce your own documentation in
-Windows Help, HTML and Word RTF formats.
-- Simple-to-use, object-oriented API.
-- Flexible event system.
-- Graphics calls include lines, rounded rectangles, splines,
-polylines, etc.
-- Constraint-based and sizer-based layouts.
-- Print/preview and document/view architectures.
-- Toolbar, notebook, tree control, advanced list control classes.
-- PostScript generation under Unix, normal MS Windows printing on the
-PC.
-- MDI (Multiple Document Interface) support.
-- Can be used to create DLLs under Windows, dynamic libraries on Unix.
-- Common dialogs for file browsing, printing, colour selection, etc.
-- Under MS Windows, support for creating metafiles and copying them to
-the clipboard.
-- An API for invoking help from applications.
-- Ready-to-use HTML window (supporting a subset of HTML).
-- Dialog Editor for building dialogs.
-- Network support via a family of socket and protocol classes.
-- Support for platform independent image processing.
-- Built-in support for many file formats (BMP, PNG, JPEG, GIF, XPM,
-PNM, PCX).
-
-
-
-
-
To set a wxPython application going, you will need to derive an App
-class and override App.OnInit.
-
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.
-
A frame can have a MenuBar, a ToolBar, a status line, and an Icon for
-when the frame is iconized.
-
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.
-
Instances of Dialog can also be used for controls, and they have the
-advantage of not requiring a separate frame.
-
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.
-
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).
-
-
Most modern applications will have an on-line, hypertext help system;
-for this, you need Help and the HelpController class to control
-Help.
-
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 wxWindows 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 wxWindows class.
-
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.
-
See also Classes by Category for a list of classes.
-
-
-
-
In addition to the core wxWindows library, a number of further
-libraries and utilities are supplied with each distribution.
-
[Need to list these.]
-
-
-
-
[This section needs to be reviewed.]
-
-
-
-
-
-
-
-
-
Classes: wx.App
-
-
-
The OnInit method defined for a class derived from wx.App will usually
-create a top window as a bare minimum.
-
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.
-
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.
-
In emergencies the wx.Exit() function can be called to kill the
-application, however, normally the application shuts down
-automatically, see below.
-
An example of defining an application follows:
-
-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()
-
-
-
-
-
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.
-
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.
-
For example, this code may crash:
-
[Need examples of objects needing cleanup to keep app from crashing.]
-
-
-
-
-
Classes: wx.Sizer, wx.GridSizer, wx.FlexGridSizer, wx.BoxSizer,
-wx.StaticBoxSizer, wx.NotebookSizer, wx.CreateButtonSizer
-
-
-
-
-
-
-| Sizer |
-Abstract base class. |
-
-| GridSizer |
-A sizer for laying out windows in a grid with all
-fields having the same size. |
-
-| FlexGridSizer |
-A sizer for laying out windows in a flexible grid. |
-
-| BoxSizer |
-A sizer for laying out windows in a row or column. |
-
-| StaticBoxSizer |
-Same as BoxSizer, but with a surrounding static box. |
-
-| NotebookSizer |
-Sizer to use with the Notebook control. |
-
-
-
-
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.
-
-
-
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.
-
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.
-
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.
-
-
-
-
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:
-
-
-
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):
-
[Need graphics]
-
-
-
-
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:
-
[Need graphics]
-
-
-
-
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:
-
[Need graphics]
-
-
-
-
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:
-
[Need graphics]
-
Within wxDesigner, this stretch factor gets set from the Option menu.
-
-
-
-
-
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:
-
[Need graphics]
-
-
-
-
StaticBoxSixer is the same as a BoxSizer, but surrounded by a static
-box. Here is a sample:
-
[Need graphics]
-
-
-
-
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:
-
[Need graphics]
-
-
-
-
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:
-
[Need graphics]
-
-
-
-
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.
-
[Need graphics]
-
-
-
-
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.
-
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.
-
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.
-
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
-(wx.ALIGN_CENTER_HORIZONTAL | wx.ALIGN_CENTER_VERTICAL). Default
-alignment is wx.ALIGN_LEFT | wx.ALIGN_TOP.
-
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 (|). 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.
-
[Show code and graphic here.]
-
-
-
-
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.
-
[Show code and graphic here.]
-
-
-
-
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.
-
[Show code and graphic here.]
-
-
-
-
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.
-
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:
-
[Show code and graphic here.]
-
-
-
-
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.
-
[Show code and graphic here.]
-
-
-
-
-
-
wxPython provides a set of powerful classes to work with dates and
-times. Some of the supported features of the DateTime class are:
-
-
-
-
-
-
-| Wide range |
-The range of supported dates goes from about 4714 B.C. to
-some 480 million years in the future. |
-
-| Precision |
-Not using floating point calculations anywhere ensures that
-the date calculations don't suffer from rounding
-errors. |
-
-| Many features |
-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. |
-
-| Efficiency |
-Objects of DateTime are small (8 bytes) and working
-with them is fast |
-
-
-
-
-
-
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.
-
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.
-
-
-
-
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.
-
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).
-
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.
-
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.
-
-
-
-
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.
-
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.
-
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).
-
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!
-
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()).
-
-
-
-
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.
-
Here is what can be done:
-
-
-
-
-
-
-| Addition |
-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. |
-
-| Subtraction |
-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. |
-
-| Multiplication |
-a TimeSpan or DateSpan object can be multiplied by an
-integer number resulting in an object of the same
-type. |
-
-| Unary minus |
-a TimeSpan or DateSpan object may finally be negated
-giving an interval of the same magnitude but of
-opposite time direction. |
-
-
-
-
-
-
-
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.
-
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.
-
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.
-
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.
-
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.
-
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
-
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());
-
-
-
-
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.
-
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.
-
The time zone handling methods use these functions too, so they are
-subject to the same limitations.
-
-
-
-
-
-
-
The source document is named wxPython.txt and is located in the
-PyCrust/wxd directory. It is written using a fantastic formatting
-convention called reStructuredText. The wxPython.html file is created
-using the Docutils utilities, which can turn reStructuredText
-documents into html, xml, pdf, and even OpenOffice files.
-
Some items in the source text file look like this:
-
-.. This is text from the wxWindows 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.
-
-
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.)
-
-
-
-
Individuals who contributed to this documentation (in order by last
-name):
-
-- Robin Dunn
-- Patrick K. O'Brien
-- Robert Roebling
-- Julian Smart
-- Vadim Zeitlin
-
-
-
-
-
This document began as a translation of the wxWindows documentation.
-As such, it adheres to the same license, which is provided here:
-
- 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.
-
-
-
-
-
