Minimal Application

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. @Html.InsertExample("wxWidgets/Basics/MinimalApp1", "https://needfulsoftwaretutorials.codeplex.com/SourceControl/latest#wxWidgets/Basics/MinimalApp1/src/MinimalApp1.h")

Project setup: Visual Studio

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

@Html.InsertSlideshow("800px", "530px", new List() { "~/Content/WxWidgets/ProjectCreation1.png", "~/Content/WxWidgets/ProjectCreation2.png" })

We then make the following modifications to the project settings:

  • We add the following two directories to the list of include directories for the headers: $(WXWIN)\include and $(WXWIN)\include\msvc.
  • We add the following directory to the list of library directories: $(WXWIN)\lib\vc_lib.

This assumes that we have added a WXWIN environment variable 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 @Html.InsertReference("MSDN: pragma comment", "https://msdn.microsoft.com/en-us/library/7f0aews7.aspx", "") defined in the C:\wxWidgets-3.0.2\include\msvc\wx\setup.h file.

wxApp

wxApp @Html.InsertReference("wxWidgets: wxApp Class Reference", "http://docs.wxwidgets.org/trunk/classwx_app.html", "") 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. @Html.InsertExample("wxWidgets/Basics/MinimalApp2", "https://needfulsoftwaretutorials.codeplex.com/SourceControl/latest#wxWidgets/Basics/MinimalApp2/src/MinimalApp2.h")

The main window of an application is typically implemented by a class derived from the wxFrame class @Html.InsertReference("wxWidgets: wxFrame Class Reference", "http://docs.wxwidgets.org/trunk/classwx_frame.html", ""). 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. @Html.InsertFigure("~/Content/WxWidgets/MinimalApp2.png", "The MinimalApp2 Application")

Further Reading

  1. wxWidgets: Hello World Example