Qt GUI

The Qt GUI module provides classes for windowing system integration, event handling, OpenGL and OpenGL ES integration, 2D graphics, basic imaging, fonts and text. These classes are used internally by Qt's user interface technologies and can also be used directly, for instance to write applications using low-level OpenGL ES graphics APIs.

For application developers writing user interfaces, Qt provides higher level API's, like Qt Quick, that are much more suitable than the enablers found in the Qt GUI module.

Using the Module

Using a Qt module requires linking against the module library, either directly or through other dependencies. Several build tools have dedicated support for this, including CMake and qmake.

Building with CMake

Use the find_package() command to locate the needed module components in the Qt5 package:

find_package(Qt5 COMPONENTS Gui REQUIRED)
target_link_libraries(mytarget Qt5::Gui)

See also the Building with CMake overview.

Building with qmake

If you use qmake to build your projects, Qt GUI is included by default. To disable Qt GUI, add the following line to your .pro file:

QT -= gui

Application Windows

The most important classes in the Qt GUI module are QGuiApplication and QWindow. A Qt application that wants to show content on screen, will need to make use of these. QGuiApplication contains the main event loop, where all events from the window system and other sources are processed and dispatched. It also handles the application's initialization and finalization.

The QWindow class represents a window in the underlying windowing system. It provides a number of virtual functions to handle events (QEvent) from the windowing system, such as touch-input, exposure, focus, key strokes and geometry changes.

2D Graphics

The Qt GUI module contains classes for 2D graphics, imaging, fonts and advanced typography.

A QWindow created with the surface type QSurface::RasterSurface can be used in combination with QBackingStore and QPainter, Qt's highly optimized 2D vector graphics API. QPainter supports drawing lines, polygons, vector paths, images and text. For more information, see Paint System and Raster Window Example.

Qt can load and save images using the QImage and QPixmap classes. By default, Qt supports the most common image formats including JPEG and PNG among others. Users can add support for additional formats via the QImageIOPlugin class. For more information, see Reading and Writing Image Files

Typography in Qt is done with QTextDocument which uses the QPainter API in combination with Qt's font classes, primarily QFont. Applications that prefer more low-level APIs to text and font handling, classes like QRawFont and QGlyphRun can be used.

OpenGL and OpenGL ES Integration

QWindow supports rendering using OpenGL and OpenGL ES, depending on what the platform supports. OpenGL rendering is enabled by setting the QWindow's surface type to QSurface::OpenGLSurface, choosing the format attributes with QSurfaceFormat, and then creating a QOpenGLContext to manage the native OpenGL context. In addition, Qt has QOpenGLPaintDevice, which enables the use of OpenGL accelerated QPainter rendering, as well as convenience classes that simplify the writing of OpenGL code and hides the complexities of extension handling and the differences between OpenGL ES 2 and desktop OpenGL. The convenience classes include QOpenGLFunctions that lets an application use all the OpenGL ES 2 functions on desktop OpenGL without having to manually resolve the OpenGL function pointers, thus allowing cross-platform development of applications targeting mobile or embedded devices, and some classes that wrap native OpenGL functionality in a simpler Qt API:

• QOpenGLBuffer
• QOpenGLFramebufferObject
• QOpenGLShaderProgram
• QOpenGLTexture
• QOpenGLDebugLogger
• QOpenGLTimerQuery
• QOpenGLVertexArrayObject

Finally, in order to provide better support for the newer versions (3.0 and higher) of OpenGL, a versioned function wrapper mechanism is also available: The QOpenGLFunction_N_N family of classes expose all the functions in a given OpenGL version and profile, allowing easy development of desktop applications relying on modern, desktop-only OpenGL features.

For more information, see the OpenGL Window Example.

The Qt GUI module also contains a few math classes to aid with the most common mathmatical operations related to 3D graphics. These classes include QMatrix4x4, QVector4D and QQuaternion

A QWindow created with the QSurface::OpenGLSurface can be used in combination with QPainter and QOpenGLPaintDevice to have OpenGL hardware accelerated 2D graphics, by sacrificing some of the visual quality.

Vulkan Integration

Qt 5.10 added support for Vulkan. This requires the presence of the LunarG Vulkan SDK.

On Windows, the SDK sets the environment variable VULKAN_SDK, which will be detected by the configure script.

On Android, Vulkan headers were added in API level 24 of the NDK.

Relevant classes:

• QVulkanDeviceFunctions
• QVulkanExtension
• QVulkanFunctions
• QVulkanInfoVector
• QVulkanInstance
• QVulkanWindow
• QVulkanWindowRenderer

For more information, see the Hello Vulkan Widget Example and the Hello Vulkan Window Example.

Drag and Drop

More info in Drag and Drop

Licenses and Attributions

Qt GUI is available under commercial licenses from The Qt Company. In addition, it is available under free software licenses. Since Qt 5.4, these free software licenses are GNU Lesser General Public License, version 3, or the GNU General Public License, version 2. See Qt Licensing for further details.

Furthermore, Qt GUI in Qt 5.12.4 may contain third-party modules under following permissive licenses:

ANGLE Library, version chromium/3280	BSD 3-clause "New" or "Revised" License
ANGLE: Array Bounds Clamper for WebKit	BSD 2-clause "Simplified" License
ANGLE: Murmurhash	Public Domain
ANGLE: Systeminfo	BSD 2-clause "Simplified" License
ANGLE: trace_event	BSD 3-clause "New" or "Revised" License
Anti-aliasing rasterizer from FreeType 2	Freetype Project License or GNU General Public License v2.0 only
Bitstream Vera Font, version 1.10	Bitstream Vera Font License
Cocoa Platform Plugin	BSD 3-clause "New" or "Revised" License
DejaVu Fonts, version 2.37	Bitstream Vera Font License
Freetype 2 - Bitmap Distribution Format (BDF) support	MIT License
Freetype 2 - Portable Compiled Format (PCF) support	MIT License
Freetype 2 - zlib	zlib License
Freetype 2, version 2.9.1	Freetype Project License or GNU General Public License v2.0 only
HarfBuzz	MIT License
HarfBuzz-NG, version 1.7.4	MIT License
IAccessible2 IDL Specification, version 1.3.0	BSD 3-clause "New" or "Revised" License
LibJPEG-turbo, version 2.0.0	Independent JPEG Group License
LibPNG, version 1.6.37	libpng License and libpng License 2
Native Style for Android	Apache License 2.0
OpenGL ES 2 Headers, version Revision 27673	MIT License
OpenGL Headers, version Revision 27684	MIT License
Pixman, version 0.17.12	MIT License
Smooth Scaling Algorithm	BSD 2-clause "Simplified" License and Imlib2 License
Vulkan API Registry, version 1.0.39	MIT License
WebGradients	MIT License
Wintab API	Custom License
XCB	MIT License
sRGB color profile icc file	International Color Consortium License

Reference

• Qt GUI C++ Classes
  • Event Classes
  • Painting Classes
  • Rendering in 3D