FindwxWidgets¶

Finds a wxWidgets installation and provides usage requirements for usage in projects:

find_package(wxWidgets [<version>] [COMPONENTS <components>...] [...])

wxWidgets (formerly known as wxWindows) is a widget toolkit and tools library for creating graphical user interfaces (GUIs) for cross-platform applications.

Added in version 3.4: Support for find_package() version argument.

Added in version 3.14: OPTIONAL_COMPONENTS support.

Components¶

wxWidgets is a modular library. This module supports components to specify the modules to use. Components can be specified with the find_package() command:

find_package(
  wxWidgets
  [COMPONENTS <components>...]
  [OPTIONAL_COMPONENTS <components>...]
)

Supported components include:

base: Finds the library that provides mandatory classes that any wxWidgets code depends on. This component is always required for applications implementing wxWidgets.
core: Finds the library that provides basic GUI classes such as GDI classes or controls.
gl: Finds the OpenGL support.
mono: Finds the wxWidgets monolithic library.
aui: Finds the Advanced User Interface docking library.
net: Finds the library that provides network access.
webview: Added in version 3.4.

Finds the library that provides rendering of web documents (HTML/CSS/JavaScript).

For a full list of supported wxWidgets components, refer to the upstream documentation.

If no components are specified, this module by default searches for core and base components.

Imported Targets¶

This module provides the following Imported Targets:

wxWidgets::wxWidgets: Added in version 3.27.

An interface imported target encapsulating the wxWidgets usage requirements for the found components, available if wxWidgets is found.

Result Variables¶

This module defines the following variables:

wxWidgets_FOUND: Boolean indicating whether (the requested version of) wxWidgets and all its requested components were found.
wxWidgets_VERSION: Added in version 4.2.

The version of the wxWidgets found.
wxWidgets_INCLUDE_DIRS: Include directories for WIN32, i.e., where to find <wx/wx.h> and <wx/setup.h>; possibly empty for Unix-like systems.
wxWidgets_LIBRARIES: Path to the wxWidgets libraries.
wxWidgets_LIBRARY_DIRS: Compile time link dirs, useful for setting rpath on Unix-like systems. Typically an empty string in WIN32 environment.
wxWidgets_DEFINITIONS: Contains compile definitions required to compile/link against WX, e.g. WXUSINGDLL.
wxWidgets_DEFINITIONS_DEBUG: Contains compile definitions required to compile/link against WX debug builds, e.g. __WXDEBUG__.
wxWidgets_CXX_FLAGS: Include directories and compiler flags for Unix-like systems, empty on Windows. Essentially the output of wx-config --cxxflags.

Hints¶

This module accepts the following variables before calling find_package(wxWidgets):

WX_CONFIG: Added in version 3.11.

Environment variable to manually specify the name of the wxWidgets library configuration provider executable that will be searched besides the default name wx-config.
WXRC_CMD: Added in version 3.11.

Environment variable to manually specify the name of the wxWidgets resource file compiler executable that will be searched besides the default name wxrc.

There are two search branches: a Windows style and a Unix style. For Windows, the following variables are searched for and set to defaults in case of multiple choices. Change them if the defaults are not desired (i.e., these are the only variables that should be changed to select a configuration):

wxWidgets_ROOT_DIR: Base wxWidgets directory (e.g., C:/wxWidgets-3.2.0).
wxWidgets_LIB_DIR: Path to wxWidgets libraries (e.g., C:/wxWidgets-3.2.0/lib/vc_x64_lib).
wxWidgets_CONFIGURATION: Configuration to use (e.g., msw, mswd, mswu, mswunivud, etc.)
wxWidgets_EXCLUDE_COMMON_LIBRARIES: Set to TRUE to exclude linking of commonly required libs (e.g., png, tiff, jpeg, zlib, webp, regex, expat, scintilla, lexilla, etc.).

For Unix style this module uses the wx-config utility. Selecting between debug/release, unicode/ansi, universal/non-universal, and static/shared is possible in the QtDialog or ccmake interfaces by turning ON/OFF the following variables:

wxWidgets_USE_DEBUG

If enabled, the wxWidgets debug build will be searched.

wxWidgets_USE_UNICODE

If enabled, the wxWidgets unicode build will be searched.

wxWidgets_USE_UNIVERSAL

If enabled, the wxWidgets universal build will be searched.

wxWidgets_USE_STATIC

If enabled, static wxWidgets libraries will be linked.

wxWidgets_CONFIG_OPTIONS

This variable can be used for all other options that need to be passed to the wx-config utility. For example, to use the base toolkit found on the system at /usr install prefix, set the variable (before calling the find_package() command) as such:

set(wxWidgets_CONFIG_OPTIONS --toolkit=base --prefix=/usr)

Deprecated Variables¶

The following variables are provided for backward compatibility:

wxWidgets_VERSION_STRING

Deprecated since version 4.2: Use wxWidgets_VERSION, which has the same value.

Added in version 3.4.

The version of the wxWidgets found.

wxWidgets_USE_FILE

Deprecated since version 4.2: Instead of using this variable, include the UsewxWidgets module directly:

include(UsewxWidgets)

The path to the UsewxWidgets module for using wxWidgets in the current directory. For example:

find_package(wxWidgets)
if(wxWidgets_FOUND)
  include(${wxWidgets_USE_FILE})
endif()

Examples¶

Example: Finding wxWidgets¶

Finding wxWidgets and making it required (if wxWidgets is not found, processing stops with an error message):

find_package(wxWidgets REQUIRED)

Example: Using Imported Target¶

Finding wxWidgets and using imported target in a project:

find_package(wxWidgets)
target_link_libraries(example PRIVATE wxWidgets::wxWidgets)

Example: Using Components¶

Finding wxWidgets and specifying components:

find_package(wxWidgets COMPONENTS gl core base OPTIONAL_COMPONENTS net)
target_link_libraries(example PRIVATE wxWidgets::wxWidgets)

Example: Monolithic wxWidgets Build¶

Sample usage with monolithic wxWidgets build:

find_package(wxWidgets COMPONENTS mono)
target_link_libraries(example PRIVATE wxWidgets::wxWidgets)

Example: Using Variables¶

Finding and using wxWidgets in CMake versions prior to 3.27, when the imported target wasn't yet available:

# Note that for MinGW users the order of libs is important.
find_package(wxWidgets COMPONENTS gl core base OPTIONAL_COMPONENTS net)

if(wxWidgets_FOUND)
  include(UsewxWidgets)
  # and for each of the project dependent executable/library targets:
  target_link_libraries(example ${wxWidgets_LIBRARIES})
endif()