Why use wxWidgets? Because you want to be able to write a GUI quickly and easily that runs across platforms. You also want to be able to use the programming language of your choice, and you want your GUI to look as good as this:

Figure 1 shows Chandler, a calendar and e-mail management program in development at the Open Source Application Foundation. It is being written using the wxWidgets toolkit. Although the original version of wxWidgets is implemented in C++, Chandler's creators are using Python with the wxPython toolkit as a wrapper so that the Python code interacts seamlessly with the C++ library. The wxWidgets toolkit uses native objects wherever possible; these objects are augmented with powerful custom widgets where they're needed. You can write a wxWidgets program that will run on a wide variety of platforms, and you can use a variety or programming languages to do it.

Getting started with wxWidgets

For this article, I start with the assumption that you've already gone to the wxWidgets home page and downloaded the relevant package for your platform. If not, see the Resources section for a link and download it now. I further assume that you've managed the commands or settings you need to integrate the wxWidgets library with your compiler or integrated development environment (IDE) of choice. If that process is still a mystery, however, the links in the Resources section will point you in the right direction for that information as well. With those tasks complete, you can focus on the code.

The backbone of a wxWidgets program consists of two main objects: the application and a frame object. You can, of course, have more than one frame. In addition, you need a handful of wxWidgets-specific macros somewhere in your code. Here's how the pieces fit together.

Link to the wxWidgets library

To link to the wxWidgets library, you must include it. Place the following line at the top of your header files:

#include "wx/wx.h"

The wx/wx.h header file contains all the wxWidgets definitions you're likely to need. If you're desperately concerned with performance, you can replace this file with include statements for the specific header files you're going to use.

Define the application class

Next, you must define an application class. In most simple cases, this class doesn't do much, but you will need a class of your own. A wxWidgets application inherits from the wxApp class, and the minimal definition is minimal, indeed:

class DemoApp : public wxApp {
public:
  virtual bool OnInit();
}

The OnInit() function is called when your application starts -- effectively, it's your main() method.

When you've defined your application class, place the following macro somewhere in your code:

IMPLEMENT_APP(DemoApp)

You would replace DemoApp with the name of your application class. This macro creates the actual main() method that wxWidgets uses. It also creates an instance of the application object and begins the initialization process.

Define the frame class

Now, define a frame class, which will represent the main window of your application. The wxWidgets parent class is wxFrame. Listing 1 shows a brief example.

class DemoFrame : public wxFrame {
public:
   DemoFrame(const wxString& title);
   void OnButtonPress(wxCommandEvent& event);

private:
   DECLARE_EVENT_TABLE()
};

To clear up the names that are likely to be unfamiliar, wxString is a wxWidgets-specific string wrapper class used for string operations throughout the wxWidgets toolkit. The toolkit declines the use of Standard Template Library (STL) classes so as not to limit wxWidgets to platforms on which STL is available. (A compile-time switch allows you to use STL as the underlying implementation, if you like.) Similarly, wxCommandEvent is one of the parent classes for events -- specifically, command events, which are higher-level events that typically relate to user actions, such as a button click or list selection. Finally, the DECLARE_EVENT_TABLE macro is required for any wxWidgets object that wants to respond to events, which definitely includes the little demo frame in this article.

Define the event table

To actually respond to events, you must define the event table within your implementation files. It's another macro, and (in our case) it looks like Listing 2.

BEGIN_EVENT_TABLE(DemoFrame, wxFrame)
   EVT_BUTTON(wxID_CLOSE,  DemoFrame::OnButtonPress)
END_EVENT_TABLE()

The BEGIN_EVENT_TABLE() macro takes two arguments: the class the event table is actually for and the immediate parent of that class. The END_EVENT_TABLE macro, as you might expect, signifies the end of the event table. In between, you can have any number of specific event macros. The example in this article has one.

The wxWidgets toolkit contains several different event macros, each corresponding to a different kind of event. In our case, EVT_BUTTON refers to a button click. The first parameter to the macro is an identifier referring to the specific button being handled. The wxID_CLOSE identifier is one of several predefined identifiers that relate to common features of an application. You use a predefined identifier here purely for convenience, although in some cases, specific identifiers are a trigger for special handling by the wxWidgets system. The second parameter to the macro is the fully qualified name of the method that should be called when the menu event is triggered. You manage all events in wxWidgets using event macros similar to the one described here.

Define your methods

At this point, it's time to start defining some methods. I show three simple methods, starting with the OnInit() startup method shown in Listing 3.

bool DemoApp::OnInit() {
   DemoFrame *frame = new DemoFrame("DeveloperWorks Demo");
   frame->Show(true);
   return true;
}

The first two lines of this method do something you would expect to happen at the start of a GUI program: they create and show a main window. The third line is actually most important to the rest of the application, however. Returning true is a signal to the rest of the wxWidgets engine that the initialization has completed successfully and the program can continue. In contrast, returning false would stop the application in its tracks and cause it to exit.

The OnInit() method references the constructor for DemoFrame. In that method, you add a button to your frame, as shown in Listing 4.

DemoFrame::DemoFrame(const wxString& title)
      : wxFrame(NULL, wxID_ANY, title) {
   wxSizer *sizer = new wxBoxSizer(wxVERTICAL);
   this->SetSizer(sizer);
   wxButton *button = new wxButton(this, wxID_CLOSE, "Click Me");
   sizer->Add(50, 50);
   sizer->Add(button, 0, wxALL, 50);
}

Before you can add the button to the frame, however, you create a sizer. Sizers are the wxWidgets equivalent of the Java programming language's layout managers: they allow you to use predefined rules to place objects in your window rather than having to set the size and position of each widget independently. In this case, you use wxBoxSizer, which lays out its component widgets in a straight line. (A box sizer can be vertical or horizontal.) After creating the sizer, you attach it to the frame with the SetSizer() method. Then, you create the button. The parameters to the button constructor are:

• The parent widget (in this case, the frame)
• An integer ID
• The label to display on the button

You don't need to explicitly add the button to the frame; merely identifying the frame as the parent container does the trick. You must explicitly add the button to the sizer, however, for the sizer's layout algorithm to be aware of it. You do that in the last line of the method, but not before adding 50 x 50 pixels of blank space at the top of the row. When you do add the button, you also tell the sizer to surround the button with a border of 50 pixels. You do that using the wxALL flag and the last argument of 50.

Define an event handler

Finally, you define the simple event handler shown in Listing 5.

void DemoFrame::OnButtonPress(wxCommandEvent& event) {
   Close(true);
}

You can't get much simpler than that. Compile them all, and you'll see the lovely window with a single button shown in Figure 2. Click the button, and the window closes. In wxWidgets, closing the last parent frame automatically exits the application, so clicking the button also results in the application exiting completely.

This example, of course, barely scratches the surface of what's possible with wxWidgets. See the Resources section for guides to further exploration.

Back to top

wxPython

While wxWidgets is a powerful toolkit, not everybody wants to deal with C++ destructors, memory management, and all the rest. Luckily, a group of talented programmers has created wrapper bindings to the wxWidgets library that are usable from other programming languages. So, even if C++ isn't your programming weapon of choice, you can still have the benefits of the wxWidgets library.

The most mature and fully developed of the wxWidgets bindings is wxPython, with which you can create wxWidgets programs using the Python programming language. Downloads are available for the Microsoft® Windows®, Mac, and Linux® platforms, and there is a fairly large and active user community. What does it look like? The Python program shown in Listing 6 creates exactly the same blank window you created earlier in C++.

#!/usr/bin/env python

import wx

class DemoApp(wx.App):

   def OnInit(self):
      frame = DemoFrame(parent=None, id=-1, title='DeveloperWorks')
      frame.Show()
      return True

class DemoFrame(wx.Frame):

   def __init__(self, parent, id, title):
      wx.Frame.__init__(self, parent, id, title)
      sizer = wx.BoxSizer(wx.VERTICAL)
      self.SetSizer(sizer)
      button = wx.Button(self, wx.ID_CLOSE, "Click Me")
      sizer.Add((50, 50))
      sizer.Add(button, 0, wx.ALL, 50)
      self.Bind(wx.EVT_BUTTON, self.OnButtonClick)

   def OnButtonClick(self, event):
      self.Close(True)

if __name__ == "__main__":
   app = DemoApp()
   app.MainLoop()

As you can see, in a program this short there's nearly a one-to-one correspondence between the C++ API calls and the wxPython calls. In both cases, you create an application object and a frame object. You also start with an OnInit() method and define similar constructors and object handlers.

The biggest difference you can see in this particular example is in the binding of events to handlers. Where the C++ version manages this binding using the event table macros, the Python version uses the Bind() method, which takes as arguments a Python object representing the event type and the actual method to be called when the event is invoked. This structure takes advantage of Python's ability to treat methods as variables and pass them as arguments in exactly the same way a string or integer would be passed.

The advantages of wxPython over the C++ wxWidgets toolkit begin to show in a longer or more complex program. Even without digressing into a debate about the relative merits of C++ and Python as programming languages, there are still some nice features specific to the wxPython version of the toolkit that may be attractive to you. The event-handling mechanism using the Bind() methods blends more easily into the wxPython version than in wxWidgets. In the Python version, it's easier to update your handlers dynamically at run time. Some complex or compound widgets, such as a tree list control or an image radio button, are standard in the wxPython toolkit but not in the C++ version. Also, wxPython contains the Py package of developer tools, which makes adding interactive debugging to your wxPython program trivial.

Back to top

wxEverythingElse

Python is not the only programming language to have a binding for accessing the wxWidgets library. Although wxPython is the most mature of the bunch, several others are worth checking out if you prefer working in a particular programming language. Let's take a quick tour through some of the other stops in wxWorld. Please note that the assessments of the stability and health of these projects is an estimate based on available materials. Many of these projects are a labor of love from one or two dedicated programmers. If you're interested in a specific language project, by all means, check it out for yourself.

wxPerl

The wxPerl binding had its last major release in June 2006. It has restarted the delivery of daily snapshots, but the available documentation is a couple of years older. The mailing list is active in the range of two or three messages a day. Binary downloads are available for Win32, Linux, and Mac OS X. In addition to the main toolkit, some extras are available, including an OpenGL wrapper and a packager for creating Mac OS X applications.

The main issue with wxPerl is translating the wxWidgets API into Perl's somewhat idiosyncratic flavor of object-oriented programming (OOP). The snippet shown in Listing 7 is somewhat similar to the frame examples shown above.

package MyFrame;

use base 'Wx::Frame';

use Wx::Event qw(EVT_BUTTON);

sub new {
   my $class = shift;
   my $self = $class->SUPER::new(undef, -1, 'Trying wxPerl',
      [-1, -1], [250, 200]);
   my $sizer = Wx::BoxSizer->new(wxVERTICAL);
   my $button = Wx::Button->new($self, -1, 'Click me!', [-1, -1],
      [-1, -1]);
   EVT_BUTTON($self, $button, \&OnButtonClick);
   $sizer->Add($button);
   $self->SetSizer($sizer);
   return $self;
}

sub OnButtonClick {
   my($self, $event) = @_;
   $self->SetTitle('You Did It');
}

This code is basically a line-by-line translation of the C++ and Python code you've already seen. In this case, the wxWidgets library comes in as a Perl package, and a EVT_BUTTON function call is used, which looks similar to the macro definitions in the C++ version.

wxRuby

The wxRuby project is in something of an awkward state. There is an early tool in which the bindings to the wxWidgets API were created by hand. This tool was last released in November 2004, and since that time, development has continued intermittently on a version that uses the more powerful Simplified Wrapper and Interface Generator (SWIG) toolkit to generate the bindings between Ruby and wxWidgets. The new version was recently described in the mailing list as being ready "Any day now . . . or maybe not for several months."

One interesting thing about wxRuby is that, unlike most other wxWidgets bindings, the developers have chosen to adjust the names of wxWidgets API calls to more closely conform to Ruby naming conventions (specifically, lower_case_with_underscores rather than the wxWidgets UpperCaseWithCamelCase). So, where all the above code examples use the SetSizer() function, wxRuby calls it set_sizer(). Beyond that, again, the portions of a wxRuby program that deal with the wxWidgets API are going to be largely similar to the examples already shown.

wxWidgets world

Other wxWidgets ports are in various stages of completion or incompletion. Here's a tour of the rest of the wxWidgets landscape:

• wxBasic is both a Basic language interpreter and a set of wxWidgets bindings. It's in the process of a coming out with a new version (the last beta release was in May 2006).
• wxEuphoria was last released in December 2005 and is a binding for the Euphoria programming language.
• wxJS is a JavaScript port of wxWidgets. It has been tested only on Windows systems and includes an executable to run the JavaScript scripts. It, too, was last released in May 2006. The developers have announced that the next version will support Linux.
• wxLua is a binding for the Lua programming language. It's cross-platform, has a relatively small footprint, and its last release was March 2006.
• The wx.NET project binds C# to wxWidgets. Its last release was July 2005.

Back to top

Explore the world

The wxWidgets world has a lot to offer programmers of all stripes. The base toolkit is flexible and capable of handling most of your GUI needs, and the various language bindings place wxWidgets within the reach of most programmers. Investigating the wxWidgets toolkit in your language of choice will help you build great-looking interfaces for your own applications.

Resources

Learn

• Cross-Platform GUI Programming with wxWidgets by Julian Smart and Kevin Hock with Stefan Csomor (Prentice Hall, 2005) is the official book on wxWidgets.
  
  
• wxPython in Action by Noel Rappin and Robin Dunn (Manning, 2006) is the official book on the wxPython wrapper.
  
  
• Online documentation for wxWidgets is available from the wxWidgets Documentation page. Other ports often use the wxWidgets documentation as a reference.
  
  
• The wxWiki page helped me set up my wxWidgets project in Apple's Xcode environment.
  
  
• In the developerWorks Linux zone, find more resources for Linux developers.
  
  
• Stay current with developerWorks technical events and Webcasts.
  
  

Get products and technologies

• The main wxWidgets toolkit is available for download from the wxWidgets site.
  
  
• You can download wxPython from the wxPython site.
  
  
• You can get more information about and download wxPerl from Sourceforge.net.
  
  
• For more information and to download wxRuby, visit the wxRuby wiki.
  
  
• More information about bindings for other programming languages are available on their respective home pages:
  • wxBasic
  • wxEuphoria
  • wxJS
  • wxLua
  • wx.NET
  
  
• Order the SEK for Linux, a two-DVD set containing the latest IBM trial software for Linux from DB2®, Lotus®, Rational®, Tivoli®, and WebSphere®.
  
  
• With IBM trial software, available for download directly from developerWorks, build your next development project on Linux.
  
  

Discuss

• The wxWidgets Support page has a variety of wxWidgets community sites, including mailing lists. There's also a wiki server.
  
  
• Mailing lists related to wxPython are available at the wxPython site.
  
  
• Check out developerWorks blogs and get involved in the developerWorks community.
  
  

About the author

Rate this article

Comments

Back to top

Table of contents

• Getting started with wxWidgets
• wxPython
• wxEverythingElse
• Explore the world
• Resources
• About the author
• Comments

Next steps from IBM

Try the XL C/C++ compilers, downloadable for free.

---

• Try: XL C/C++ for AIX
• Community: Go to Rational C/C++ cafe to join the conversation.
• Buy: XL C/C++ for AIX

Dig deeper into Linux on developerWorks

Discover knowledge paths

Skill-building guides for Linux, open source, cloud, Java, business analytics, and more.

Special offers