Department of Engineering

wxWidgets

wxWidgets is a way to write Graphical User Interfaces (GUIs, with buttons, menus, etc) for Win32, Mac OS X, etc from C++, Python, Perl, and C#/.NET. It's used in our IIA Software Engineering Project. Though it's cross-platform, the resulting programs don't look the same on all machines - they follow the look-and-feel of the machine.

This document briefly introduces wxWidgets when used with C++, highlighting a few issues that sometimes puzzle newcomers.

Programming style

Whereas other graphics libraries we use at CUED (OpenGL and GLUT) aren't Object-Oriented, wxWidgets is, so you need some awareness of using C++ classes.

wxWidgets also uses Macros: they're not difficult, but you may not have seen them before. By convention they have upper-case names (e.g. IMPLEMENT_APP). They're not functions - the pre-processor expands them into "inline" C/C++ before the code reaches the compiler. Here's an example of writing and using a macro to convert Celsius to Fahrenheit

#define CTOF(x) ((x*1.8) +32)
...
float fboilingpoint=CTOF(100);

Concepts

• Widgets (things - windows, buttons, etc). These have properties like color, size, etc. Some widgets (e.g. frames) can have other widgets inside them. wxGLCanvas is a useful widget that allows you to use OpenGL commands in a window. This lets you use advanced graphics. For simpler drawing you can use the wxDC widget.
• Events (triggering actions - keypresses, window resizing, mouse clicks, etc). When an event happens, your program might want to react to it. You can arrange for particular events in certain widgets to cause a routine to run. These routines are refered to as "callbacks" or "handlers".
• Sizers - these are layout managers: they organise widgets when they're within other widgets. If for example you have a row of buttons in a panel, you don't have to calculate sizes and coordinates when the main window is resized. If you specify for each button a minimal size, a stretch factor, a border, and what's to the left of it, the sizer routine will manage the re-drawing.

Programs with GUIs often have quite a different organisation to non-GUI programs. wxWidgets-based programs for example don't even have have an explicit main procedure. What you do is create the widgets and set things up so that the appropriate callbacks are called. Then you call the main event-loop, giving control over to the application. From then on, the program waits for events. When they happen, the program calls the appropriate callback then waits for the next event. Exiting the loop exits from the program.

Writing a program

Here are the main steps. Full code is in the next section

• You first need to create a class derived from wxWidgets' wxApp class. Here's an example.

  class MyApp: public wxApp
  {
   public:
    bool OnInit(); // automatically called when the application starts
  };
  

  Then calling the macro

  IMPLEMENT_APP(MyApp)
  

  will create an object of that type and call its OnInit() member function.
• You'll need to write the OnInit function, which would normally create windows. Here's a minimal example which uses a routine from the GLUT library, a library with some routines that might be useful later -

    glutInit(&argc, argv);
    MyFrame *frame = new MyFrame(NULL, "Testing", wxDefaultPosition,  wxSize(250, 150));
    frame->Show(true);
    return(true); // enter the GUI event loop
  

• Create the frame class -

  class MyFrame: public wxFrame
  ...
  

  The wxFrame class provides a frame window - a window whose size can be changed. The MyFrame class constructor is where various widgets will be created.
• Then deal with events - an "event table" like the one below tells wxWidgets how to map events to member functions.

  DECLARE_EVENT_TABLE
  BEGIN_EVENT_TABLE(MyFrame, wxFrame)
    EVT_MENU(wxID_EXIT, MyFrame::OnExit)
    EVT_BUTTON(1, MyFrame::OnButton1)
    EVT_BUTTON(2, MyFrame::OnButton2)
  END_EVENT_TABLE()
    

  The BEGIN_EVENT_TABLE macro declares that MyFrame, which is derived from wxFrame, owns this event table.
• Write the handlers - The type of parameter given to the handlers depends on the event. For size events, wxSizeEvent is used. For menu commands and most control commands (e.g. a button), wxCommandEvent is used.

Compiling an example

This compile line

 g++ -o foo foo.cc  `wx-config --unicode=no --cxxflags` `wx-config --unicode=no --libs` -lglut -lGL -lGLU

// Adapted from an example by Dr Gee (CUED)
#include <wx/wx.h>
#include <GL/glut.h>
#include <iostream>

class MyFrame: public wxFrame
{
 public:
  MyFrame(wxWindow *parent, const wxString& title, const wxPoint& pos, 
          const wxSize& size);
 private:
  void OnExit(wxCommandEvent& event) { Close(true); };   
  void OnButton1(wxCommandEvent& event) {
       std::cout << "Button 1 Pressed" << std::endl;
  }; 
  void OnButton2(wxCommandEvent& event) {
       std::cout << "Button 2 Pressed" << std::endl;
  };
  DECLARE_EVENT_TABLE()
};
    
BEGIN_EVENT_TABLE(MyFrame, wxFrame)
  EVT_MENU(wxID_EXIT, MyFrame::OnExit)
  EVT_BUTTON(1, MyFrame::OnButton1)
  EVT_BUTTON(2, MyFrame::OnButton2)
END_EVENT_TABLE()
  
MyFrame::MyFrame(wxWindow *parent, const wxString& title, const wxPoint& pos, 
         const wxSize& size):
  wxFrame(parent, wxID_ANY, title, pos, size)
{
  wxMenu *fileMenu = new wxMenu;
  // The '&' in the next line underlines the succeeding character 
  fileMenu->Append(wxID_EXIT, "&Quit");
  wxMenuBar *menuBar = new wxMenuBar;

  menuBar->Append(fileMenu, "&File");
  SetMenuBar(menuBar);

  wxBoxSizer *button_sizer = new wxBoxSizer(wxHORIZONTAL);
  button_sizer->Add(new wxButton(this, 1, "button 1"), 0, 
                wxALL, 10);
  button_sizer->Add(new wxButton(this, 2, "button 2"), 0, 
                wxALL, 10);
  button_sizer->Add(new wxStaticText(this, wxID_ANY, "Some Text"), 0, 
                wxTOP|wxLEFT|wxRIGHT, 10);
 SetSizer(button_sizer);
}

class MyApp: public wxApp
{
 public:
  bool OnInit() {
  glutInit(&argc, argv);
  MyFrame *frame = new MyFrame(NULL, "Testing", wxDefaultPosition,  
                       wxSize(250, 150));
  frame->Show(true);
  return(true); // enter the GUI event loop
  };
};

IMPLEMENT_APP(MyApp)

MyFrame::MyFrame(....):
  wxFrame(parent, wxID_ANY, title, pos, size)

When a derived object is created, it will by default first call the default constructor of the class it's derived from. In this case however, we don't want to call wxFrame's default constructor, we want to pass some arguments down. It's a constructor "with a member initialiser list"

Troubleshooting

If your program compiles but doesn't work properly

• Start from an example that works.
• Check to see if you're using a faultly implementation - the code's supposed to work the same on all platforms, but that's not always so in practise.
• Code that works with one version of wXwidgets may not work with another. For example, wxFD_OPEN only appeared in version 2.8. To write code that works with new and older versions you can try using wxFD_OPEN and adding

  #if (wxMINOR_VERSION < 8)
  #define wxFD_OPEN wxOPEN
  #endif 
  

  to your source
• Note that unless wXwidgets is installed with the --with-opengl configure option, the wxGLCanvas class (which displays OpenGL graphics) won't be supported.

Strings

You've already met C strings (character arrays) and C++ strings (the string data type). wXwidgets has its own string type called wxString which they suggest you use throughout your program - it has better internationalisation support as well as the features that C++ strings offer. See Converting everything to and from wxString for further information. To convert from a C++ string to a wxString you can try the following

  string s="hello";
  wxString mystring(s.c_str(), wxConvUTF8);

Sources of wxWidgets information

• wxWiki main page
• A simple Tutorial
• A list of classes sorted by category
• Overviews

See Also

• Using GLUT
• Using GLUI (a simpler way to produce simple GUIs)
• Using GLUE (a simple way to produce simple graphical programs with buttons)
• OpenGL