Figure 2-1 shows what our sample looks like under Windows.

Figure 2-1 Minimal sample under Windows

The minimal wxWidgets application shows a main window (a wxFrame) with a menu bar and status bar. The menus allow you to show an “about box” or quit the program. Not exactly a killer app, but it’s enough to show some of the basic principles of wxWidgets—and to reassure you that you can start simple and work your way up to a complete application as your confidence and expertise grow.

Every wxWidgets application defines an application class deriving from wxApp. There is only one instance of it, and this instance represents the running application. At the very least, your class should define an OnInit function that will be called when wxWidgets is ready to start running your code (equivalent to main or WinMain when writing a C or Win32 application).

Here is the smallest application class declaration you can sensibly write:

The implementation of OnInit usually creates at least one window, interprets any command-line arguments, sets up data for the application, and performs any other initialization tasks required for the application. If the function returns true, wxWidgets starts the event loop that processes user input and runs event handlers as necessary. If the function returns false, wxWidgets will clean up its internal structures, and the application will terminate.

A simple implementation of OnInit might look like this:

This creates an instance of our new class MyFrame (we’ll define this class shortly), shows it, and returns true to start the event loop. Unlike child windows, top-level windows such as frames and dialogs need to be shown explicitly after creation.

The frame title is passed to the constructor wrapped in the wxT() macro. You’ll see this used a lot in wxWidgets samples and in the library code itself—it converts string and character literals to the appropriate type to allow the application to be compiled in Unicode mode. This macro is also known by the alias _T(). There is no run-time performance penalty for using it. (You’ll also see the underscore macro _() used to enclose strings, which tells wxWidgets to translate the string. See Chapter 16, “Writing International Applications,” for more details.)

Where is the code that creates the instance of MyApp? wxWidgets does this internally, but you still need to tell wxWidgets what kind of object to create. So you need to add a macro in your implementation file:

Without specifying the class, wxWidgets would not know how to create a new application object. This macro also inserts code that checks that the application and library were compiled using the same build configuration, allowing wxWidgets to report accidental mismatches that might later cause a hard-to-debug run-time failure.

When wxWidgets creates a MyApp object, it assigns the result to the global variable wxTheApp. You can use this in your application, but it would be more convenient if you didn’t have to cast the wxApp pointer to MyApp. By inserting this macro after your application class declaration:

you can then call the function wxGetApp, which returns a reference to the MyApp object.

Let’s look at the frame class MyFrame. A frame is a top-level window that contains other windows, and usually has a title bar and menu bar. Here’s our simple frame class declaration that we will put after the declaration of MyApp:

Our frame class has a constructor, two event handlers to link menu commands to C++ code, and a macro to tell wxWidgets that this class handles events.

As you may have noticed, the event handler functions in MyFrame are not virtual and should not be virtual. How, then, are they called? The answer lies in the event table, as follows.

An event table, placed in a class’s implementation file, tells wxWidgets how events coming from the user or from other sources are routed to member functions.

With the event table shown previously, mouse clicks on menu items with the identifiers wxID_EXIT and wxID_ABOUT are routed to the functions MyFrame::OnQuit and MyFrame::OnAbout, respectively. EVT_MENU is just one of many event table macros you can use to tell wxWidgets what kind of event should be routed to what function. The identifiers used here are predefined by wxWidgets, but you will often define your own identifiers, using enums, consts, or preprocessor defines.

This kind of event table is a static way of routing events, and cannot be changed at runtime. In the next chapter, we’ll describe how to set up dynamic event handlers.

While we’re dealing with event tables, let’s see the two functions we’re using as event handlers.

MyFrame::OnAbout shows a message box when the user clicks on the About menu item. wxMessageBox takes a message, a caption, a combination of styles, and a parent window.

MyFrame::OnQuit is called when the user clicks on the Quit menu item, thanks to the event table. It calls Close to destroy the frame, triggering the shutdown of the application, because there are no other frames. In fact, Close doesn’t directly destroy the frame—it generates a wxEVT_CLOSE_WINDOW event, and the default handler for this event destroys the frame using wxWindow::Destroy.

There’s another way the frame can be closed and the application shut down—the user can click on the close button on the frame, or select Close from the system (or window manager) menu. How does OnQuit get called in this case? Well, it doesn’t—instead, wxWidgets sends a wxEVT_CLOSE_WINDOW event to the frame via Close (as used in OnQuit). wxWidgets handles this event by default and destroys the window. Your application can override this behavior and provide its own event handler—for example, if you want to ask the user for confirmation before closing. For more details, please see Chapter 4, “Window Basics.”

This sample doesn’t need it, but most applications should provide an OnExit function in its application class to clean up data structures before quitting. Note that this function is only called if OnInit returns true.

Finally, we have the frame constructor, which implements the frame icon, a menu bar, and a status bar.

This constructor calls the base constructor with the parent window (none, hence NULL), window identifier, and title. The identifier argument is wxID_ANY, which tells wxWidgets to generate an identifier itself. The base constructor creates the actual window associated with the C++ instance—another way to achieve this is to call the default constructor of the base class, and then explicitly call wxFrame::Create from within the MyFrame constructor.

Small bitmaps and icons can be implemented using the XPM format on all platforms. XPM files have valid C++ syntax and so can be included as shown previously; the SetIcon line creates an icon on the stack using the C++ variable mondrian_xpm defined in mondrian.xpm, and associates it with the frame.

The menu bar is created next. Menu items are added using the identifier (such as the standard identifier wxID_ABOUT), the label to be displayed, and a help string to be shown on the status bar. Within each label, a mnemonic letter is marked by a preceding ampersand, and an accelerator is preceded by the tab character ( ). A mnemonic is the letter a user presses to highlight a particular item when the menu is displayed. An accelerator is a key combination (such as Alt+X) that can be used to perform that action without showing the menu at all.

The last thing that the constructor does is to create a status bar with two fields at the bottom of the frame and set the first field to the string “Welcome to wxWidgets!”

It’s worth putting together the bits so you can see what the whole program looks like. Normally, you’d have a separate header file and implementation file, but for such a simple program, we can put it all in the same file.