This page shows a very simple wxWidgets program that can be used as a skeleton for your own code.
While this program does nothing very useful, it introduces a couple of important concepts and explains how to write a working wxWidgets application. Trying building and running this application is also a good way of checking that wxWidgets is correctly installed on your system. And if you haven't installed wxWidgets yet, please do it first.
Without further ado, let's write our first application.
First, you have to include wxWidgets' header files, of course. This can be done on a file by file basis (such as wx/frame.h
) or using one global include (wx/wx.h
) which includes most of the commonly needed headers (although not all of them as there are simply too many wxWidgets headers to pull in all of them).
Execution of a "classic" C++ program starts in its main()
function (putting aside the constructors of the global objects), but GUI applications must use a different "entry function" on some platforms (such as WinMain()
used under Microsoft Windows). wxWidgets provides a convenient wxIMPLEMENT_APP() macro, which allows to define the appropriate entry function on all platforms. Please note that you can avoid using macros if you're so inclined by defining your own entry function and using wxInitializer class for the library initialization, but this example won't do it for brevity and simplicity.
This macro takes a single parameter which is the name of the application class, that must be defined in the program. This class must derive from wxApp and, at the very least, override wxApp::OnInit() virtual function, as it will be called by wxWidgets to initialize the application. Let's do this:
The main window of a typical application is a wxFrame object. While it's possible to just use this class directly, it's usually more convenient to derive a custom class from it, as this allows to store additional data and handle events (such as mouse clicks, messages from the menu, or a button) in the methods of this class — allowing them to access this data easily.
So, even if we don't have any data in this toy example, let's define such a custom class with a few "event handlers", i.e. functions taking the event
parameter of the type corresponding to the event being handled, which is wxCommandEvent for the events from simple controls such as buttons, text fields and also menu items. In our example, we react to three menu items: our custom "Hello", and the "Exit" and "About" items (any program should normally implement the latter two). Notice that these handlers don't need to be virtual or public.
Now that we have this class, we can implement OnInit()
which, as you remember, is called upon application startup and simply create the main window, represented by this class, in it:
Please note the following points:
Show()
to make this happen.OnInit()
allows the application to start running. By default, it will exit once all top-level windows have been closed (but see wxApp::SetExitOnFrameDelete()), so this function should normally create at least one window (but can, of course, create more than one). Otherwise it can just return false to exit immediately instead.In the constructor of the main window, we create a menu with our menu items, as well as a status bar to be shown at the bottom of the main window.
In order to be able to react to a menu command, it must be given a unique identifier which can be defined as a constant or an enum element. The latter is often used because typically many such constants will be needed:
Notice that you don't need to define identifiers for "About" and "Exit", as wxWidgets already predefines standard values such as wxID_ABOUT and wxID_EXIT (see Stock Items for the full list). You should use these whenever possible, as they can be handled in a special way by a particular platform and also have predefined labels associated with them, which allows us to omit them when appending the corresponding menu items. For our custom item, we specify the label, also containing an accelerator, separated by Tab
from the label itself, allowing to invoke this command from keyboard:
Note that, as with the windows, menu pointers don't need to (and, in fact, must not) be destroyed because they are owned by the menu bar, which is itself owned by the frame, which is owned, i.e. will be destroyed, by wxWidgets.
We also have to connect our event handlers to the events we want to handle in them. We do this by calling Bind() to send all the menu events (identified by wxEVT_MENU event type) with the specified ID to the given function. The parameters we pass to Bind() are
this
pointer for the object itself. We could instead call the method of another object, or a non-member function — in fact, any object that can be called with a wxCommandEvent, can be used here.Here are the standard event handlers implementations. MyFrame::OnExit() closes the main window by calling Close(). The parameter 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 application will quit.
MyFrame::OnAbout() will display a small window with some text in it. In this case a typical "About" window with information about the program.
The implementation of custom menu command handler may perform whatever task your program needs to do, in this case we will simply show a message from it as befits a Hello World example:
Here is the entire program that can be copied and pasted: