The Application Class

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:

 // Declare the application class class MyApp : public wxApp { public:     // Called on application startup     virtual bool OnInit(); }; 

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:

 bool MyApp::OnInit() {     // Create the main application window     MyFrame *frame = new MyFrame(wxT("Minimal wxWidgets App"));     // Show it     frame->Show(true);     // Start the event loop     return true; } 

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 itselfit 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:

 // Give wxWidgets the means to create a MyApp object IMPLEMENT_APP(MyApp) 

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:

 // Implements MyApp& wxGetApp() DECLARE_APP(MyApp) 

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

Tip

Even if you don't use DECLARE_APP, you can still use the variable wxTheApp to call wxApp functions. This will avoid the need to include your specific application header. It can be useful within code (such as a library) that doesn't know about specific application classes, and to save compilation time.