The dope on Wax

What is Wax?

Simply put, Wax is a GUI toolkit. It sits on top of wxPython, removing some of the low-level aspects of that GUI, and adding some useful abstractions.

The goal is that Wax should be easier to use than wxPython, but just as feature-rich. Maybe even more so.

The actual situation is different. Frankly, I don't have the time to work on this project very much. That's why I only add new features when I need them. Some of my other projects (Firedrop, Sourcery, etc) use Wax, so over time, when I need more controls, I add them. On the other hand, a subset of controls is there, and is usable.

Still, you might find that controls you want are missing, or even other features like certain events. But see below.

Note that I am "growing" this toolkit rather than trying to release a complete package that is ready for everyday use.

What are the benefits?

As said, Wax aims to take away some of the low-level aspects of wxPython. This is implemented in several ways:

1. It's no longer necessary to make up IDs and pass them around. You just create an object like you would expect:

b = Button(parent, "click me")

2. Events are just methods that can be changed at will. Sometimes they can be passed in an object's constructor. They can always be changed later. For example, for Buttons you change the OnClick method:

b = Button(parent, "click me", event=myevent)
# later...
b.OnClick = yourevent

3. Easy setting of exception hook: in the main frame of the application, you can set a magic method named __ExceptHook__, which deals with uncaught exceptions. For example (code from examples/excepthook1.py):

from wax import *

class MainFrame(Frame):
    def Body(self):
        self.AddComponent(Button(self, "one", event=self.OnClick))
        self.Pack()
    def OnClick(self, event=None):
        # deliberately create an error
        x = 1/0
    def __ExceptHook__(self, exctype, value, traceback):
        dlg = ErrorDialog(self, exctype, value, traceback)
        dlg.ShowModal()
        dlg.Destroy()

app = Application(MainFrame)
app.MainLoop()

This code also demonstrates how easy it is to get a working base for your program.

4. Easy sizers: Wax has a couple of container controls, most notably Frame and Panel, with sizers built-in. Here's a simple example (examples/simplebuttons.py):

from wax import *

WaxConfig.default_font = ("Verdana", 9)

class MainFrame(Frame):
    def Body(self):
        self.AddComponent(Button(self, "one"), stretch=1)
        self.AddComponent(Button(self, "two"), expand=1)
        self.AddComponent(Button(self, "three"))
        self.Pack()

app = Application(MainFrame)
app.MainLoop()

By default, a Frame has a horizontal sizer, meaning that controls added to it will be lined up horizontally. In this example, the three buttons will appear next to each other. When you resize the window, button "one" will expand vertically, "two" will expand horizontally, and "three" will keep its size.

The sizing and packing mechanism is a bit reminiscent of Tkinter's. Add components, then pack them. Like Tkinter, and unlike wxPython, Wax offers an easy way to make your own controls using Frames and Panels.

5. Special variables (like, for example, wxTE_MULTILINE, etc) are, whenever possible, replaced with methods and function arguments. For example, here's a TextBox that has multiple lines, can be edited, wraps long lines, and is left-justified:

tb = TextBox(parent, size=(400, 200), multiline=1, 
     readonly=0, wrap=1, justify='left')

There are more benefits, but these are the most important ones.

How does it work?

A more elaborate explanation will follow later. For now, suffice to say that most Wax controls are subclasses of wxPython controls. They get a new name, new constructor, new methods. Sometimes they are thin wrappers, sometimes the behavior is changed significantly (e.g. Panels and Frames).

Where is the documentation?

Unfortunately, there is no documentation at the moment. I plan to write at least some how-to documents to get people started.

Wax isn't difficult to use, and for now, adventurous people can use the source (especially the examples directory). The wxPython/wxWindows documentation will also come in handy; since almost all Wax controls derive from wxPython controls, they will still have most of the same methods.

Where can I download it?

The latest version is available in the download section.

How do I install it?

No fancy (?) distutils installer for now. The directory wax in the zip file is a package. Stick it wherever Python can see it; lib/site-packages may be a good choice. Then test it by starting up an interactive interpreter and type

from wax import *

If that works, you're all set.

What are the requirements?

Python 2.3, although it might work with older versions. And wxPython, of course. I currently use version 2.6.1.0; any other recent version *might* work as well, but then again it might not.

Feature X is missing. When will you add it?

It depends. Wax is very much a work in progress. If I happen to need a lot of new controls for whatever project I'm working on, then Wax will benefit and grow fast. But if that isn't the case, then growth might stagnate.

If adding the feature is not much work, then I might find time for it and stick it in the next release, even if I have no immediate need for it.

What I am hoping for is that some people will find Wax useful, and add some missing features or controls. That way, it will become rapidly more useful. Adding a new control is not difficult; I'll add a how-to for this later.

I want to contribute a feature/control. Are there any guidelines?

The most important Wax guideline is "simplicity counts". Right now I am mostly interested in common GUI stuff, wrappers around wxPython controls, that should be (very) simple to use.

A new control should *at least* get rid of the wxPython ID (if any) and add some events (like it is done in other Wax controls). I don't like gratuitous wrappers, though; if at all possible, it should contain some new, useful (high-level) methods.

Any special stuff that will be added in the future?

Not sure, but I would really like to add data-aware components like Delphi has. Also, eventually we need something to use a different layout than horizontal and vertical sizers.