Contents

QGuiApplication Class

The QGuiApplication class manages the GUI application's control flow and main settings. More...

Header: #include <QGuiApplication>
qmake: QT += gui
Since: Qt 5.0
Inherits: QCoreApplication
Inherited By:

QApplication

This class was introduced in Qt 5.0.

Properties

Signals

void applicationDisplayNameChanged()
void layoutDirectionChanged(Qt::LayoutDirection direction)
void primaryScreenChanged(QScreen *screen)

Static Public Members

QString applicationDisplayName()
QString desktopFileName()
Qt::LayoutDirection layoutDirection()
QString platformName()
QScreen *primaryScreen()
bool quitOnLastWindowClosed()
void setApplicationDisplayName(const QString &name)
void setDesktopFileName(const QString &name)
void setLayoutDirection(Qt::LayoutDirection direction)
void setQuitOnLastWindowClosed(bool quit)
void setWindowIcon(const QIcon &icon)
QIcon windowIcon()

Macros

qGuiApp

Detailed Description

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, and provides session management. In addition, QGuiApplication handles most of the system-wide and application-wide settings.

For any GUI application using Qt, there is precisely one QGuiApplication object no matter whether the application has 0, 1, 2 or more windows at any given time. For non-GUI Qt applications, use QCoreApplication instead, as it does not depend on the Qt GUI module. For QWidget based Qt applications, use QApplication instead, as it provides some functionality needed for creating QWidget instances.

The QGuiApplication object is accessible through the instance() function, which returns a pointer equivalent to the global qApp pointer.

QGuiApplication's main areas of responsibility are:

  • It initializes the application with the user's desktop settings, such as palette(), font() and styleHints(). It keeps track of these properties in case the user changes the desktop globally, for example, through some kind of control panel.
  • It performs event handling, meaning that it receives events from the underlying window system and dispatches them to the relevant widgets. You can send your own events to windows by using sendEvent() and postEvent().
  • It parses common command line arguments and sets its internal state accordingly. See the constructor documentation below for more details.
  • It provides localization of strings that are visible to the user via translate().
  • It provides some magical objects like the clipboard().
  • It knows about the application's windows. You can ask which window is at a certain position using topLevelAt(), get a list of topLevelWindows(), etc.
  • It manages the application's mouse cursor handling, see setOverrideCursor()
  • It provides support for sophisticated session management. This makes it possible for applications to terminate gracefully when the user logs out, to cancel a shutdown process if termination isn't possible and even to preserve the entire application's state for a future session. See isSessionRestored(), sessionId() and commitDataRequest() and saveStateRequest() for details.

Since the QGuiApplication object does so much initialization, it must be created before any other objects related to the user interface are created. QGuiApplication also deals with common command line arguments. Hence, it is usually a good idea to create it before any interpretation or modification of argv is done in the application itself.

Groups of functions
System settingsdesktopSettingsAware(), setDesktopSettingsAware(), styleHints(), palette(), setPalette(), font(), setFont().
Event handlingexec(), processEvents(), exit(), quit(). sendEvent(), postEvent(), sendPostedEvents(), removePostedEvents(), hasPendingEvents(), notify().
WindowsallWindows(), topLevelWindows(), focusWindow(), clipboard(), topLevelAt().
Advanced cursor handlingoverrideCursor(), setOverrideCursor(), restoreOverrideCursor().
Session managementisSessionRestored(), sessionId(), commitDataRequest(), saveStateRequest().
MiscellaneousstartingUp(), closingDown().

See also QCoreApplication, QAbstractEventDispatcher, and QEventLoop.

Property Documentation

applicationDisplayName : QString

This property holds the user-visible name of this application

This name is shown to the user, for instance in window titles. It can be translated, if necessary.

If not set, the application display name defaults to the application name.

This property was introduced in Qt 5.0.

Access functions:

QString applicationDisplayName()
void setApplicationDisplayName(const QString &name)

Notifier signal:

void applicationDisplayNameChanged()

See also applicationName.

desktopFileName : QString

This property holds the base name of the desktop entry for this application

This is the file name, without the full path, of the desktop entry that represents this application according to the freedesktop desktop entry specification.

This property gives a precise indication of what desktop entry represents the application and it is needed by the windowing system to retrieve such information without resorting to imprecise heuristics.

The latest version of the freedesktop desktop entry specification can be obtained here.

This property was introduced in Qt 5.7.

Access functions:

QString desktopFileName()
void setDesktopFileName(const QString &name)

layoutDirection : Qt::LayoutDirection

This property holds the default layout direction for this application

On system start-up, the default layout direction depends on the application's language.

The notifier signal was introduced in Qt 5.4.

Access functions:

Qt::LayoutDirection layoutDirection()
void setLayoutDirection(Qt::LayoutDirection direction)

Notifier signal:

void layoutDirectionChanged(Qt::LayoutDirection direction)

See also QWidget::layoutDirection, isLeftToRight(), and isRightToLeft().

platformName : const QString

This property holds the name of the underlying platform plugin.

The QPA platform plugins are located in qtbase\src\plugins\platforms. At the time of writing, the following platform plugin names are supported:

  • android
  • cocoa is a platform plugin for macOS.
  • directfb
  • eglfs is a platform plugin for running Qt5 applications on top of EGL and OpenGL ES 2.0 without an actual windowing system (like X11 or Wayland). For more information, see EGLFS.
  • ios (also used for tvOS)
  • kms is an experimental platform plugin using kernel modesetting and DRM (Direct Rendering Manager).
  • linuxfb writes directly to the framebuffer. For more information, see LinuxFB.
  • minimal is provided as an examples for developers who want to write their own platform plugins. However, you can use the plugin to run GUI applications in environments without a GUI, such as servers.
  • minimalegl is an example plugin.
  • offscreen
  • openwfd
  • qnx
  • windows
  • wayland is a platform plugin for modern Linux desktops and some embedded systems.
  • xcb is the X11 plugin used on regular desktop Linux platforms.

For more information about the platform plugins for embedded Linux devices, see Qt for Embedded Linux.

Access functions:

QString platformName()

primaryScreen : QScreen* const

This property holds the primary (or default) screen of the application.

This will be the screen where QWindows are initially shown, unless otherwise specified.

The primaryScreenChanged signal was introduced in Qt 5.6.

Access functions:

QScreen *primaryScreen()

Notifier signal:

void primaryScreenChanged(QScreen *screen)

See also screens().

quitOnLastWindowClosed : bool

This property holds whether the application implicitly quits when the last window is closed.

The default is true.

If this property is true, the applications quits when the last visible primary window (i.e. window with no parent) is closed.

Access functions:

bool quitOnLastWindowClosed()
void setQuitOnLastWindowClosed(bool quit)

See also quit() and QWindow::close().

windowIcon : QIcon

This property holds the default window icon

Access functions:

QIcon windowIcon()
void setWindowIcon(const QIcon &icon)

See also QWindow::setIcon() and Setting the Application Icon.

Macro Documentation

qGuiApp

A global pointer referring to the unique application object. Only valid for use when that object is a QGuiApplication.

See also QCoreApplication::instance() and qApp.

© 2022 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners.
The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation.
Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.