Hello World

This is a tiny tutorial by Robert Roebling.

It aims to help people make quick judgements concerning syntax and basic principles. The complete Hello World program is here.

You have to include wxWidgets's header files, of course. This can be done on a file by file basis (such as #include "wx/window.h") or using one global include (#include "wx/wx.h"). This is also useful on platforms which support precompiled headers such as all major compilers on the Windows platform.


#include "wx/wx.h"

Practically every app should define a new class derived from wxApp. By overriding wxApp's OnInit() the program can be initialized, e.g. by creating a new main window.

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

The main window is created by deriving a class from wxFrame and giving it a menu and a status bar in its constructor. Also, any class that wishes to respond to any "event" (such as mouse clicks or messages from the menu or a button) must declare an event table using the macro below. Finally, the way to react to such events must be done in "handlers". In our sample, we react to two menu items, one for "Quit" and one for displaying an "About" window. These handlers should not be virtual.

class MyFrame: public wxFrame
{
public:

MyFrame(const wxString& title, const wxPoint& pos, const wxSize& size);

void OnQuit(wxCommandEvent& event);
void OnAbout(wxCommandEvent& event);

DECLARE_EVENT_TABLE()
};

In order to be able to react to a menu command, it must be given a unique identifier such as a const or an enum.

enum
{
ID_Quit = 1,
ID_About,
};

We then procede to actually implement an event table in which the events are routed to their respective handler functions in the class MyFrame. There are predefined macros for routing all common events, ranging from the selection of a list box entry to a resize event when a user resizes a window on the screen.

BEGIN_EVENT_TABLE(MyFrame, wxFrame)
EVT_MENU(ID_Quit, MyFrame::OnQuit)
EVT_MENU(ID_About, MyFrame::OnAbout)
END_EVENT_TABLE()

As in all programs there must be a "main" function. Under wxWidgets main is implemented using this macro, which creates an application instance and starts the program.

IMPLEMENT_APP(MyApp)

As mentionend above, wxApp::OnInit() is called upon startup and should be used to initialize the program, maybe showing a "splash screen" and creating the main window (or several). The frame should get a title bar text ("Hello World") and a position and start-up size. One frame can also be declared to be the top window. Returning TRUE indicates a successful intialization.

bool MyApp::OnInit()
{
MyFrame *frame = new MyFrame( "Hello World", wxPoint(50,50), wxSize(450,340) );
frame->Show(TRUE);
SetTopWindow(frame);
return TRUE;
}

In the constructor of the main window (or later on) we create a menu with two menu items as well as a status bar to be shown at the bottom of the main window. Both have to be "announced" to the frame with respective calls.

MyFrame::MyFrame(const wxString& title, const wxPoint& pos, const wxSize& size)
: wxFrame((wxFrame *)NULL, -1, title, pos, size)
{
wxMenu *menuFile = new wxMenu;

menuFile->Append( ID_About, "&About..." );
menuFile->AppendSeparator();
menuFile->Append( ID_Quit, "E&xit" );

wxMenuBar *menuBar = new wxMenuBar;
menuBar->Append( menuFile, "&File" );

SetMenuBar( menuBar );

CreateStatusBar();
SetStatusText( "Welcome to wxWidgets!" );
}

Here are the actual event handlers. MyFrame::OnQuit() closes the main window by calling Close(). The paramter TRUE indicates that other windows have no veto power such as after asking "Do you really want to close?". If there is no other main window left, the applicatin will quit.

void MyFrame::OnQuit(wxCommandEvent& WXUNUSED(event))
{
Close(TRUE);
}

MyFrame::OnAbout() will display a small window with some text in it. In this case a typical "About" window with information about the program.

void MyFrame::OnAbout(wxCommandEvent& WXUNUSED(event))
{
wxMessageBox("This is a wxWidgets Hello world sample",
"About Hello World", wxOK | wxICON_INFORMATION, this);
}

You might want to compile the program. Give the source text a .cpp ending, such as hworld.cpp. With wxGTK and its configure system, you can use the following the following statement on any system that has g++ (wherever you installed GTK+ and wxGTK and whatever option you used upon installation). If you use another port such as wxMotif or wxMSW, it is recommended that you adapt one of the sample makefiles or project files.

g++ hworld.cpp `wx-config --libs` `wx-config --cxxflags` -o hworld

Finally, you might want to start the program with:

./hworld

At this point the program comes up and you can exit it or show the dialog.

A note for wxGTK users: if the program doesn't start and you get a message like "hworld: can't load library libwx_gtk.so.1" then you forgot to rerun the linker after installing the library. Do that by logging in as root and run "ldconfig" (on Linux and Solaris). If you get an instant error from your X server and then a crash, then you compiled your library with thread support although your system doesn't support it. You'll have to configure --without-threads and recompile all of wxGTK after a "make clean".

For people who don't like the way to route events to handlers done using event tables but rather prefer the way it's done in GTK+ or Qt: there is a Connect() method available also, which functions in much the same way as in GTK+. An argument against using Connect() (although being more C++ and shorter to write) is that wxIDE, wxWidgets' visual programming environment will use (and modify) the method tables, not the Connect() routines.

A version of hworld using Connect() is here.