WxWidgets Source Code Overview
This document provides an overview of the wxWidgets source code structure for a new wxWidgets developer.
Before reading this document, you should read pages 8-13 of the book “Cross-Platform GUI Programming with wxWidgets” by Julian Smart, Kevin Hock, and Stefan Csomor, Prentice Hall, 2006. Those six pages give you the big picture of the various ports and then this document will fill in some of the lower level details.
Understanding the source code landscape will help you in these ways
- When you are working to fix bugs in your own code, your debugger will often step through unfamiliar areas of the wxWidgets source code
- You may want to work on the wxWidgets source code yourself some day
In this document, the path to a header file (*.h) will always be relative to the “include” directory and the path to a source file (*.cpp, *.c, *.mm) will always be relative to the “src” directory. Examples
- wx/button.h will be found in the wxWidgets directory “include/wx/button.h”
- gtk/button.cpp will be found in the wxWidgets directory “src/gtk/button.cpp”
As shown in Table 1-1 on page 8 of the book, wxWidgets uses many layers of code to provide a consistent programming API across many operating systems. When you develop an application using the public wxWidgets API, you can compile the application on many operating systems without needing to be an expert in any of those operating systems. The layers can be best understood by studying some examples.
This example demonstrates a very basic element which is common to every graphical user interface. The public interface is defined by the documentation for wxButton in the reference manual https://docs.wxwidgets.org/trunk/classwx_button.html The source code is then implemented with the following files
- This file defines the common features of a button in wxButtonBase and then, depending on operating system, it includes the operating system dependent definition of a button such as wx/msw/button.h, wx/osx/button.h or wx/gtk/button.h
- This file defines the interface for a wxButton on Microsoft Windows. Note that wxButton inherits from wxButtonBase to obtain all of the common button features.
- This file defines the interface for a wxButton on Mac OS X again inheriting from wxButtonBase
Compare wx/msw/button.h to wx/osx/button.h and you will see some key differences. Both files implement the same public interface as defined in the reference manual. However, they each add additional methods to the wxButton class as required by their respective operating systems.
- This file is the source code for wxButtonBase which provides the core features for a wxButton that are common to all platforms.
- This file is the source code for the implementation of wxButton on Microsoft Windows using Windows concepts such as SendMessage, SetWindowLong, etc.
- This file is the base source code for the implementation of wxButton on Mac OS X. However on this operating system, there are two core libraries to consider: The older Carbon library and the newer Cocoa library.
- This file is the Carbon implementation of wxButton written in C++.
- This file is the Cocoa implementation of wxButton written in Objective C.
This example demonstrates a complex control which is found on some platforms but not others. wxWidgets uses the native control if it is available and creates a generic control for platforms which have no native control. The public interface is defined by the documentation for wxCalendarCtrl in the reference manual at https://docs.wxwidgets.org/trunk/classwx_calendar_ctrl.html The source code is then implemented with the following files
- As in the prior example, this file defines the common features in wxCalendarCtrlBase and then includes the operating system dependent definition from other files. In this case, only Microsoft Windows and GTK 2.0 have a suitable native control and all other platforms use a generic control.
- Provides the native definition of wxCalendarCtrl for Microsoft Windows, inheriting some base functionality from wxCalendarCtrlBase
- Provides the native definition of wxCalendarCtrl for Linux GTK 2.0, inheriting some base functionality from wxCalendarBase
- Provides a generic calendar control for all other platforms.
- Provides the implementation for wxCalendarCtrlBase for all platforms.
- Provides the implementation of the native control on Microsoft Windows.
- Provides the implementation of the native control on Linux GTK 2.0.
- Provides a generic calendar control for platforms which do not have a native version.
After studying the two examples above, the directory structure becomes more clear. The library can be divided into platform independent code and platform dependent code.
Platform Independent Code
- include/wx (excluding subdirectories of include/wx)
- This code is common across platforms and defines the base implementation of each widget in the wxWidgets library.
- This code provides generic widgets for platforms which have no equivalent native widget. As an example, only Mac OS X has a native wxSearchCtrl so all other platforms use a generic implementation.
- Provides support for Advanced User Interfaces (AUI)
- Provides support for DirectFB for hardware graphic acceleration, translucent windows and multiple display layers.
- Provides support for HTML presentation
- Provides support for Property Grids for editing property sheets
- Provides support for the Ribbon which replaces the Toolbar in applications such as Microsoft Office.
- Provides an text control for fancy fonts including special fonts and colors
- Provides support for the Scintilla source code editing component
- Provides a means to construct user interfaces from XML resources.
- Provides support for XML parsing
- Provides persistence for objects
- Provides constructs for metaprogramming
- Provides FTP protocols
Third Party Libraries
These libraries provide useful features for all platforms. Note that the header files have not been split off into include/wx because it is desirable to keep the entire third party library in one place:
- Provides support for images in Tag Image File Format (TIFF) files.
- Provides support for images in Portable Network Graphics (PNG) files.
- Provides support for images in Joint Photographic Experts Group (JPEG) files.
- Provides support for Regular Expression matching such as wildcards
- Provides support for data compression in gzip formats.
- Provides support for parsing Extensible Markup Language (XML) files
Platform Dependent Code
- Code for supporting Microsoft Windows
Linux and Unix
- Code for supporting GTK+ including GTK 1.x and 2.x. GTK is quite popular and therefore this is the recommended port for Linux and Unix.
- Code for generic Unix features that are independent of the window manager
- Code for supporting the X11 window manager
- Code for supporting the Motif window manager
Mac OS X and iOS
- Common code for OSX and iOS, but not using native APIs
- Common code for OSX and iOS, using native APIs that exist on all platforms, like CoreFoundation for example.
- Code for supporting Mac OS X Cocoa. This is the main port for wx on OS X going forward.
- Code for supporting Mac OS X Carbon. Carbon is older than Cocoa and is no longer actively developed by Apple. Similarly there is no active development in this wxWidgets Carbon port.
- iOS port, wx-base is working, while the GUI part is still in its infancy
- Provides basic widgets for small platforms which have none of their own.
Rarely Used or Obsolete Code
- An older version of Mac OS X Cocoa which has been superseded by the newer libraries mentioned above.
- An older library supporting Microsoft MS DOS
- An older library supporting IBM OS/2
- An older library supporting PalmOne Palm O/S
- An older library supporting GTK 1.0 now superseded by GTK 2.0 in the newer libraries mentioned above.
- An older library supporting MGL, a graphic library for game development
As described in the examples above, each widget is defined by its description in the reference manual https://docs.wxwidgets.org/trunk/classes.html Each port strives to implement that widget description on a particular operating system.
The files used to create this documentation are
- Header files for the documentation
- A script which checks the syntax of the header files.
- Instructions for building the wxWidgets documentation using DOxygen
Unit tests are essential to the quality of wxWidgets
The files used for unit tests are
- Directory of unit tests for wxWidgets
- Instructions for writing unit tests using CppUnit