Introduction to wxWidgets

last modified July 14, 2026

This tutorial introduces you to the programming with the wxWidgets toolkit.

wxWidgets

wxWidgets is a graphical user interface (GUI) toolkit for creating C++ applications. It is an open source, mature, and cross-platform toolkit. wxWidgets applications run on all major OS platforms, including Windows, Unix, and macOS. The project was started by Julian Smart in 1992 at the University of Edinburgh. The latest stable release is version 3.2.11. wxWidgets is much more than a toolkit. It provides a large variety of classes for handling streams, databases, threads, online help, or application settings. wxWidgets consists of a large group of widgets. The community around wxWidgets gathers on their website.

The C++ programming language

The C++ programming language is one of the most widely used programming languages. It is used in many famous desktop applications such as MS Office, Photoshop, Chrome, Firefox, and MongoDB. C++ also dominates the world of PC games. It is one of the more complex programming languages. On the other hand, modern C++ (C++11 and later) offers many features that make programming safer and more productive, such as smart pointers, lambda expressions, and the STL.

Multiplatform programming

Today, multiplatform programming is a common requirement. wxWidgets was created as a cross-platform tool from the beginning. Developers have several options for building GUI applications. If possible, they may go to the web. For native desktop applications, they can use Qt, wxWidgets, or Flutter. The Qt library is the closest competitor to wxWidgets.

Installing wxWidgets from packages

On many Linux distributions, wxWidgets can be installed directly from the official package repositories. The package names and availability vary by distribution.

On Debian-based systems (Debian, Ubuntu, Linux Mint), the wxWidgets 3.2 development package is named libwxgtk3.2-dev:

$ sudo apt install libwxgtk3.2-dev

On Fedora-based systems, the wxWidgets package is named wxGTK-devel:

$ sudo dnf install wxGTK-devel

On openSUSE, the package is called wxWidgets-3_2-devel:

$ sudo zypper install wxWidgets-3_2-devel

Installing from packages is the quickest way to get started. However, the packaged version may not be the latest release. For the most recent version, building from source is recommended.

Installing wxWidgets on Windows

On Windows, wxWidgets can be installed using the vcpkg package manager, which handles both the library and its dependencies. Alternatively, it can be built from the source distribution manually with Microsoft Visual Studio.

If using vcpkg, first install vcpkg and then install wxWidgets:

> git clone https://github.com/Microsoft/vcpkg.git
> cd vcpkg
> .\bootstrap-vcpkg.bat
> .\vcpkg install wxwidgets --triplet x64-windows

The --triplet x64-windows option targets 64-bit Windows. Use x86-windows for 32-bit builds. After installation, integrate vcpkg with Visual Studio:

> .\vcpkg integrate install

To build wxWidgets manually, download the source archive from the releases page and extract it. Open a Visual Studio developer command prompt and navigate to the build/msw directory inside the extracted source tree:

> cd wxWidgets-3.2.11\build\msw
> nmake -f makefile.vc

This builds the wxWidgets libraries for the default platform. The resulting libraries and DLLs are placed in the lib\vc_dll directory. To use wxWidgets in your Visual Studio projects, set the WXWIN environment variable to the path of the wxWidgets root directory. Additional build configurations, such as static linking or debug builds, are available via nmake options.

Building wxWidgets from source on Linux

The following instructions walk through building wxWidgets 3.2.11 from source on a Debian-based Linux distribution.

First, install the C++ compiler and required development libraries:

$ sudo apt install build-essential libgtk-3-dev libjpeg-dev libpng-dev \
    libtiff-dev libgl1-mesa-dev libglu1-mesa-dev libnotify-dev \
    libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev \
    libwebkit2gtk-4.1-dev

We install the C++ compiler, the GTK+ 3 development headers, image format libraries (libjpeg, libpng, libtiff), OpenGL libraries for graphics rendering, libnotify for desktop notifications, GStreamer for multimedia support, and WebKit2GTK for web view integration.

Download the wxWidgets source code:

$ wget https://github.com/wxWidgets/wxWidgets/releases/download/v3.2.11/wxWidgets-3.2.11.tar.bz2
$ tar -xf wxWidgets-3.2.11.tar.bz2
$ cd wxWidgets-3.2.11/

Create a separate build directory and configure the build:

$ mkdir build-gtk && cd build-gtk
$ ../configure --with-gtk=3 --enable-unicode --enable-shared --with-opengl

The configure command detects the system configuration and prepares the build. The --with-gtk=3 option selects the GTK+ 3 toolkit, --enable-unicode enables Unicode support, --enable-shared builds shared libraries, and --with-opengl enables OpenGL support.

Build and install wxWidgets:

$ make -j$(nproc)
$ sudo make install

The make -j$(nproc) command compiles the library using all available CPU cores. After building, we run sudo make install to install the libraries and headers to the system. On Linux, we then need to run sudo ldconfig to update the shared library cache.

Finally, verify the installation:

$ wx-config --version
3.2.11

The wx-config utility reports the installed version of wxWidgets. It is also used to obtain the compiler and linker flags needed to build wxWidgets applications.

Setting up wxWidgets in VS Code

To develop wxWidgets applications in Visual Studio Code, we need to configure the C++ extension so that it can locate the wxWidgets headers and define the necessary preprocessor macros.

First, install the C/C++ extension by Microsoft from the VS Code marketplace. Then, in the project's .vscode directory, create a file named c_cpp_properties.json with the following content:

{
    "configurations": [
        {
            "name": "Linux",
            "includePath": [
                "${workspaceFolder}/**",
                "/usr/local/lib/wx/include/gtk3-unicode-3.2",
                "/usr/local/include/wx-3.2"
            ],
            "defines": [
                "_FILE_OFFSET_BITS=64",
                "WXUSINGDLL",
                "__WXGTK__"
            ],
            "compilerPath": "/usr/bin/g++",
            "cStandard": "c17",
            "cppStandard": "c++17",
            "intelliSenseMode": "linux-gcc-x64"
        }
    ],
    "version": 4
}

The includePath tells the IntelliSense engine where to find the wxWidgets header files. The defines section sets the preprocessor macros required by wxWidgets, such as __WXGTK__ (identifying the GTK+ port) and WXUSINGDLL (indicating that we are using the shared library build). Adjust the compilerPath and include paths if your wxWidgets installation resides in a different location.

With this configuration, VS Code provides full IntelliSense, code completion, and syntax highlighting for wxWidgets applications.

This was an introduction to wxWidgets.

Ebooks