wxWidgets Tutorial (1/3)

In tutorial we show how to start writing applications with wxWidgets [1].

Setup

The wxWidgets framework is made of set of C++ header files and libraries. Precompiled versions of the libraries exist for some platforms but the recommended way to set up the wxWidgets framework is to compile the libraries yourself. This is the method we will show here.

The precompiled libraries and the source code are available from the wxWidgets download page [2].

Setup on Windows for Visual Studio

As of January 2015 the latest stable release is 3.0.2. We will assume that the source code archive for 3.0.2 has been unpacked in C:\wxWidgets-3.0.2.

wxWidgets provides project files for most of the Visual Studio versions. They are located in C:\wxWidgets-3.0.2\build\msw and the source files are located in C:\wxWidgets-3.0.2\src. In this page we will be using Visual Studio 2013 so we load the corresponding project file: C:\wxWidgets-3.0.2\build\msw\wx_vc12.sln.

Four build configurations are defined in each project file: Debug, Release, DLL Debug and DLL Release. The Debug and Release configurations build a static version of the wxWidgets libraries while the DLL Debug and DLL Release configurations build the wxWidgets as DLLs.

Both the static and dynamic configurations use the DLL version of the C++ runtime library. The choice of configuration only determines whether the wxWidgets code itself is linked into a static library or a DLL.

In this tutorial the examples will use the static libraries so we build the Debug and Release configurations. The build puts the header files into C:\wxWidgets-3.0.2\include and the libraries in C:\wxWidgets-3.0.2\lib\vc_lib.

First Minimal Application

We will start with an example of a minimal application that build successfully but doesn't start properly. The goal is to show the basic setup needed to get the application to build successfully. The full example is available from our Codeplex repository at wxWidgets/Basics/MinimalApp1.

Project setup: Visual Studio

We create the new project using the Visual C++ Win32 Project template.

We then make the following modifications to the project settings:

This assumes that we have added a WXWIN environment that points to the directory where we installed the wxWidgets headers and libraries: C:\wxWidgets-3.0.2 in our case.

It may be surprising that we are not adding any libraries to the list of libraries to link against. That is because the required libraries are included by means of a series of #pragma comment(lib, <path>) statements [3] defined in the C:\wxWidgets-3.0.2\include\msvc\wx\setup.h file.

wxApp

wxApp [4] is the class that represents the application itself. Typically an application implements a class derived from wxApp and override the wxApp::OnInit() method to initialize the GUI.

The declaration of the class derived from wxApp for our example is shown below. It simples derives from wxApp and overrides the OnInit() method.

File: wxWidgets/Basics/MinimalApp1/src/MinimalApp1.h
#ifndef _TUTORIALS_WXWIDGETS_MINIMALAPP1_H_
#define _TUTORIALS_WXWIDGETS_MINIMALAPP1_H_

#include <wx/app.h>

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

#endif

The wxIMPLEMENT_APP macro must be used to provide the entry point. In a wxWidgets application you don't implement the main (or WinMain) function yourself, you only implement the class derived from wxApp and you let the wxIMPLEMENT_APP macro provide the main function.

The OnInit() method would typically initialize the user interface and return true to indicate success. In this first example we just want to show the minimum needed for the application to compile successfully so we return false. Returning false will cause the application to exit.

The implementation of the MinimalApp1 class is shown below.

File: wxWidgets/Basics/MinimalApp1/src/MinimalApp1.cpp
#include "MinimalApp1.h"

wxIMPLEMENT_APP(MinimalApp1);

bool MinimalApp1::OnInit()
{
    // Normally you would initialize the UI here
    // and return true on success
    return false;
}

Our first example is now complete. It should build successfully. If you run the application it will start and exit right away without showing any UI.

Second Minimal Application

Let's now enhance our first example so that it displays a single window that can be closed.

The initial steps to create this second example are identical to the first one. The full example is available from our Codeplex repository at wxWidgets/Basics/MinimalApp2.

The main window of an application is typically implemented by a class derived from the wxFrame class [5]. The code for the main window for the MinimalApp2 application is shown below.

File: wxWidgets/Basics/MinimalApp2/src/MinimalApp2Frame.h
#ifndef _TUTORIALS_WXWIDGETS_MINIMALAPP2FRAME_H_
#define _TUTORIALS_WXWIDGETS_MINIMALAPP2FRAME_H_

#include <wx/frame.h>

class MinimalApp2Frame : public wxFrame
{
public:
    MinimalApp2Frame(const wxString& title);
};

#endif
File: wxWidgets/Basics/MinimalApp2/src/MinimalApp2Frame.cpp
#include "MinimalApp2Frame.h"

MinimalApp2Frame::MinimalApp2Frame(const wxString& title)
    : wxFrame(NULL, wxID_ANY, title)
{
}

We then modify the OnInit() function to create and show a new instance of MinimalApp2Frame. The file is shown below. The lines that are identical to MinimalApp1 (except for the trivial rename to MinimalApp2) have been greyed out.

File: wxWidgets/Basics/MinimalApp2/src/MinimalApp2.cpp
#include "MinimalApp2.h"
#include "MinimalApp2Frame.h"

wxIMPLEMENT_APP(MinimalApp2);

bool MinimalApp2::OnInit()
{
    MinimalApp2Frame* frame = new MinimalApp2Frame("MinimalApp2");
    frame->Show(true);
    return true;
}

For completeness we also show MinimalApp2.h but there are no significant changes compared to MinimalApp1.h.

File: wxWidgets/Basics/MinimalApp2/src/MinimalApp2.h
#ifndef _TUTORIALS_WXWIDGETS_MINIMALAPP2_H_
#define _TUTORIALS_WXWIDGETS_MINIMALAPP2_H_

#include <wx/app.h>

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

#endif

If we compile and run this application a basic frame will be displayed. It can already handle some actions like minimizing, maximizing or closing the frame. By default closing the last frame of an application will also close the application itself. Figure 1 shows the MinimalApp2 application.

The MinimalApp2 Application
Figure 1: The MinimalApp2 Application

References

  1. wxWidgets Home Page
  2. wxWidgets download page
  3. MSDN: pragma comment
  4. wxWidgets: wxApp Class Reference
  5. wxWidgets: wxFrame Class Reference

Further Reading

  1. wxWidgets: Hello World Example

blog comments powered by Disqus

Copyright(c) 2006-2017 Xavier Leclercq | Privacy policy

Home
Contact Us
Search