QGuiApplication¶

PyQt5.QtGui.QGuiApplication

Description¶

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

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 __init__() 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 settings	desktopSettingsAware(), setDesktopSettingsAware(), styleHints(), palette(), setPalette(), font(), setFont().
Event handling	exec(), processEvents(), exit(), quit(). sendEvent(), postEvent(), sendPostedEvents(), removePostedEvents(), hasPendingEvents(), notify().
Windows	allWindows(), topLevelWindows(), focusWindow(), clipboard(), topLevelAt().
Advanced cursor handling	overrideCursor(), setOverrideCursor(), restoreOverrideCursor().
Session management	isSessionRestored(), sessionId(), commitDataRequest, saveStateRequest.
Miscellaneous	startingUp(), closingDown().

Methods¶

__init__(List[str]): TODO

@staticmethod allWindows() → List[QWindow]: TODO

@staticmethod applicationDisplayName() → str: See also

setApplicationDisplayName().

@staticmethod applicationState() → ApplicationState: TODO

@staticmethod changeOverrideCursor(Union[QCursor, CursorShape])

Changes the currently active application override cursor to cursor.

This function has no effect if setOverrideCursor() was not called.

@staticmethod clipboard() → QClipboard: Returns the object for interacting with the clipboard.

@staticmethod desktopFileName() → str: See also

setDesktopFileName().

@staticmethod desktopSettingsAware() → bool: Returns true if Qt is set to use the system’s standard colors, fonts, etc.; otherwise returns false. The default is true.

See also

setDesktopSettingsAware().

devicePixelRatio() → float

Returns the highest screen device pixel ratio found on the system. This is the ratio between physical pixels and device-independent pixels.

Use this function only when you don’t know which window you are targeting. If you do know the target window, use devicePixelRatio() instead.

See also

devicePixelRatio().

event(QEvent) → bool: TODO

@staticmethod exec() → int

Enters the main event loop and waits until exit() is called, and then returns the value that was set to exit() (which is 0 if exit() is called via quit()).

It is necessary to call this function to start event handling. The main event loop receives events from the window system and dispatches these to the application widgets.

Generally, no user interaction can take place before calling .

To make your application perform idle processing, e.g., executing a special function whenever there are no pending events, use a QTimer with 0 timeout. More advanced idle processing schemes can be achieved using processEvents().

We recommend that you connect clean-up code to the aboutToQuit signal, instead of putting it in your application’s main() function. This is because, on some platforms, the QApplication::exec() call may not return.

See also

quitOnLastWindowClosed(), quit(), exit(), processEvents(), exec().

@staticmethod exec_() → int

Enters the main event loop and waits until exit() is called, and then returns the value that was set to exit() (which is 0 if exit() is called via quit()).

It is necessary to call this function to start event handling. The main event loop receives events from the window system and dispatches these to the application widgets.

Generally, no user interaction can take place before calling .

To make your application perform idle processing, e.g., executing a special function whenever there are no pending events, use a QTimer with 0 timeout. More advanced idle processing schemes can be achieved using processEvents().

We recommend that you connect clean-up code to the aboutToQuit signal, instead of putting it in your application’s main() function. This is because, on some platforms, the QApplication::exec() call may not return.

See also

quitOnLastWindowClosed(), quit(), exit(), processEvents(), exec().

@staticmethod focusObject() → QObject: Returns the QObject in currently active window that will be final receiver of events tied to focus, such as key events.

@staticmethod focusWindow() → QWindow: Returns the QWindow that receives events tied to focus, such as key events.

@staticmethod font() → QFont: Returns the default application font.

See also

setFont().

@staticmethod highDpiScaleFactorRoundingPolicy() → HighDpiScaleFactorRoundingPolicy: TODO

@staticmethod inputMethod() → QInputMethod

returns the input method.

The input method returns properties about the state and position of the virtual keyboard. It also provides information about the position of the current focused input element.

See also

QInputMethod.

@staticmethod isFallbackSessionManagementEnabled() → bool

Returns whether QGuiApplication will use fallback session management.

The default is true.

If this is true and the session manager allows user interaction, QGuiApplication will try to close toplevel windows after commitDataRequest has been emitted. If a window cannot be closed, session shutdown will be canceled and the application will keep running.

Fallback session management only benefits applications that have an “are you sure you want to close this window?” feature or other logic that prevents closing a toplevel window depending on certain conditions, and that do nothing to explicitly implement session management. In applications that do implement session management using the proper session management API, fallback session management interferes and may break session management logic.

Warning: If all windows are closed due to fallback session management and quitOnLastWindowClosed() is true, the application will quit before it is explicitly instructed to quit through the platform’s session management protocol. That violation of protocol may prevent the platform session manager from saving application state.

@staticmethod isLeftToRight() → bool: TODO

@staticmethod isRightToLeft() → bool: TODO

isSavingSession() → bool: TODO

isSessionRestored() → bool: TODO

@staticmethod keyboardModifiers() → KeyboardModifiers

Returns the current state of the modifier keys on the keyboard. The current state is updated sychronously as the event queue is emptied of events that will spontaneously change the keyboard state (KeyPress and KeyRelease events).

It should be noted this may not reflect the actual keys held on the input device at the time of calling but rather the modifiers as last reported in one of the above events. If no keys are being held NoModifier is returned.

@staticmethod layoutDirection() → LayoutDirection: See also

setLayoutDirection().

@staticmethod modalWindow() → QWindow

Returns the most recently shown modal window. If no modal windows are visible, this function returns zero.

A modal window is a window which has its modality() property set to WindowModal or ApplicationModal. A modal window must be closed before the user can continue with other parts of the program.

Modal window are organized in a stack. This function returns the modal window at the top of the stack.

See also

WindowModality, setModality().

@staticmethod mouseButtons() → MouseButtons

Returns the current state of the buttons on the mouse. The current state is updated synchronously as the event queue is emptied of events that will spontaneously change the mouse state (MouseButtonPress and MouseButtonRelease events).

It should be noted this may not reflect the actual buttons held on the input device at the time of calling but rather the mouse buttons as last reported in one of the above events. If no mouse buttons are being held NoButton is returned.

See also

keyboardModifiers().

notify(QObject, QEvent) → bool: TODO

@staticmethod overrideCursor() → QCursor: See also

setOverrideCursor().

@staticmethod palette() → QPalette: Returns the default application palette.

See also

setPalette().

@staticmethod platformName() → str: TODO

@staticmethod primaryScreen() → QScreen: TODO

@staticmethod queryKeyboardModifiers() → KeyboardModifiers: TODO

@staticmethod quitOnLastWindowClosed() → bool: See also

setQuitOnLastWindowClosed().

@staticmethod restoreOverrideCursor(): TODO

@staticmethod screenAt(QPoint) → QScreen

Returns the screen at point, or nullptr if outside of any screen.

The point is in relation to the virtualGeometry() of each set of virtual siblings. If the point maps to more than one set of virtual siblings the first match is returned.

@staticmethod screens() → List[QScreen]: Returns a list of all the screens associated with the windowing system the application is connected to.

sessionId() → str: TODO

sessionKey() → str: TODO

@staticmethod setApplicationDisplayName(str): See also

applicationDisplayName().

@staticmethod setDesktopFileName(str): See also

desktopFileName().

@staticmethod setDesktopSettingsAware(bool)

Sets whether Qt should use the system’s standard colors, fonts, etc., to on. By default, this is true.

This function must be called before creating the QGuiApplication object, like this:

# int main(int argc, char *argv[])
# {
#     QApplication::setDesktopSettingsAware(false);
#     QApplication app(argc, argv);
#     ...
#     return app.exec();
# }

See also

desktopSettingsAware().

@staticmethod setFallbackSessionManagementEnabled(bool): Sets whether QGuiApplication will use fallback session management to enabled.

See also

isFallbackSessionManagementEnabled().

@staticmethod setFont(QFont): Changes the default application font to font.

See also

font().

@staticmethod setHighDpiScaleFactorRoundingPolicy(HighDpiScaleFactorRoundingPolicy): TODO

@staticmethod setLayoutDirection(LayoutDirection): See also

layoutDirection().

@staticmethod setOverrideCursor(Union[QCursor, CursorShape]): See also

overrideCursor().

@staticmethod setPalette(QPalette): Changes the default application palette to pal.

See also

palette().

@staticmethod setQuitOnLastWindowClosed(bool): See also

quitOnLastWindowClosed().

@staticmethod setWindowIcon(QIcon): See also

windowIcon().

@staticmethod styleHints() → QStyleHints

Returns the application’s style hints.

The style hints encapsulate a set of platform dependent properties such as double click intervals, full width selection and others.

The hints can be used to integrate tighter with the underlying platform.

See also

QStyleHints.

@staticmethod sync()

Function that can be used to sync Qt state with the Window Systems state.

This function will first empty Qts events by calling processEvents(), then the platform plugin will sync up with the windowsystem, and finally Qts events will be delived by another call to processEvents();

This function is timeconsuming and its use is discouraged.

@staticmethod topLevelAt(QPoint) → QWindow: Returns the top level window at the given position pos, if any.

@staticmethod topLevelWindows() → List[QWindow]: TODO

@staticmethod windowIcon() → QIcon: See also

setWindowIcon().

Signals¶

applicationDisplayNameChanged(): TODO

applicationStateChanged(ApplicationState): TODO

commitDataRequest(QSessionManager): TODO

focusObjectChanged(QObject): TODO

focusWindowChanged(QWindow): TODO

fontChanged(QFont): TODO

fontDatabaseChanged(): TODO

lastWindowClosed(): TODO

layoutDirectionChanged(LayoutDirection): TODO

paletteChanged(QPalette): TODO

primaryScreenChanged(QScreen): TODO

saveStateRequest(QSessionManager): TODO

screenAdded(QScreen): TODO

screenRemoved(QScreen): TODO