WxWidgets Source Code Overview

From WxWiki
Jump to: navigation, search

Introduction

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”

Code Structure

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.

Example: wxButton

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

wx/button.h
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
wx/msw/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.
wx/osx/button.h
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.

common/btncmn.cpp
This file is the source code for wxButtonBase which provides the core features for a wxButton that are common to all platforms.
msw/button.cpp
This file is the source code for the implementation of wxButton on Microsoft Windows using Windows concepts such as SendMessage, SetWindowLong, etc.
osx/button_osx.cpp
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.
  • osx/carbon/button.cpp
    This file is the Carbon implementation of wxButton written in C++.
  • osx/cocoa/button.mm
    This file is the Cocoa implementation of wxButton written in Objective C.

Example: wxCalendarCtrl

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

wx/calctrl.h
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.
wx/msw/calctrl.h
Provides the native definition of wxCalendarCtrl for Microsoft Windows, inheriting some base functionality from wxCalendarCtrlBase
wx/gtk/calctrl.h
Provides the native definition of wxCalendarCtrl for Linux GTK 2.0, inheriting some base functionality from wxCalendarBase
wx/generic/calctrlg.h
Provides a generic calendar control for all other platforms.
common/calctrlcmn.cpp
Provides the implementation for wxCalendarCtrlBase for all platforms.
wx/msw/calctrl.cpp
Provides the implementation of the native control on Microsoft Windows.
wx/gtk/calctrl.cpp
Provides the implementation of the native control on Linux GTK 2.0.
wx/generic/calctrl.cpp
Provides a generic calendar control for platforms which do not have a native version.

Directory Structure

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

Base Code

include/wx (excluding subdirectories of include/wx)
src/common
This code is common across platforms and defines the base implementation of each widget in the wxWidgets library.

Generic Code

include/wx/generic
src/generic
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.

Sub-Libraries

include/wx/aui
src/aui
Provides support for Advanced User Interfaces (AUI)
include/wx/dfb
src/dfb
Provides support for DirectFB for hardware graphic acceleration, translucent windows and multiple display layers.
include/wx/html
src/html
Provides support for HTML presentation
include/wx/propgrid
src/propgrid
Provides support for Property Grids for editing property sheets
include/wx/ribbon
src/ribbon
Provides support for the Ribbon which replaces the Toolbar in applications such as Microsoft Office.
include/wx/richtext
src/richtext
Provides an text control for fancy fonts including special fonts and colors
include/wx/stc
src/stc
Provides support for the Scintilla source code editing component
include/wx/xrc
src/xrc
Provides a means to construct user interfaces from XML resources.
include/wx/xml
src/xml
Provides support for XML parsing
include/wx/persist
Provides persistence for objects
include/wx/meta
Provides constructs for metaprogramming
include/wx/protocol
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:

src/tiff
Provides support for images in Tag Image File Format (TIFF) files.
src/png
Provides support for images in Portable Network Graphics (PNG) files.
src/jpeg
Provides support for images in Joint Photographic Experts Group (JPEG) files.
src/regex
Provides support for Regular Expression matching such as wildcards
src/zlib
Provides support for data compression in gzip formats.
src/expat
Provides support for parsing Extensible Markup Language (XML) files

Platform Dependent Code

Microsoft Windows

include/wx/msw
include/msvc
src/msw
Code for supporting Microsoft Windows

Linux and Unix

include/wx/gtk
src/gtk
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.
include/wx/unix
src/unix
Code for generic Unix features that are independent of the window manager
include/wx/x11
src/x11
Code for supporting the X11 window manager
include/wx/motif
src/motif
Code for supporting the Motif window manager

Mac OS X and iOS

include/wx/osx
src/osx
Common code for OSX and iOS, but not using native APIs
include/wx/osx/core
src/osx/core
Common code for OSX and iOS, using native APIs that exist on all platforms, like CoreFoundation for example.
include/wx/osx/cocoa
src/osx/cocoa
Code for supporting Mac OS X Cocoa. This is the main port for wx on OS X going forward.
include/wx/osx/carbon
src/osx/carbon
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.
include/wx/osx/iphone
src/osx/iphone
iOS port, wx-base is working, while the GUI part is still in its infancy

Universal

include/wx/univ
src/univ
Provides basic widgets for small platforms which have none of their own.

Rarely Used or Obsolete Code

include/wx/cocoa
src/cocoa
An older version of Mac OS X Cocoa which has been superseded by the newer libraries mentioned above.
include/wx/msdos
src/msdos
An older library supporting Microsoft MS DOS
include/wx/os2
src/os2
An older library supporting IBM OS/2
include/wx/palmos
src/palmos
An older library supporting PalmOne Palm O/S
include/wx/gtk1
src/gtk1
An older library supporting GTK 1.0 now superseded by GTK 2.0 in the newer libraries mentioned above.
include/wx/mgl
src/mgl
An older library supporting MGL, a graphic library for game development

Documentation

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

interface/wx
Header files for the documentation
interface/check_syntax.sh
A script which checks the syntax of the header files.
docs/tech/tn0003.txt
Instructions for building the wxWidgets documentation using DOxygen

Tests

Unit tests are essential to the quality of wxWidgets

The files used for unit tests are

tests/
Directory of unit tests for wxWidgets
docs/tech/tn0017.txt
Instructions for writing unit tests using CppUnit