QWindow Class

Member Function Documentation

[explicit] QWindow::QWindow(QScreen *targetScreen = nullptr)

Creates a window as a top level on the targetScreen.

The window is not shown until setVisible(true), show(), or similar is called.

See also setScreen().

[explicit] QWindow::QWindow(QWindow *parent)

Creates a window as a child of the given parent window.

The window will be embedded inside the parent window, its coordinates relative to the parent.

The screen is inherited from the parent.

See also setParent().

[virtual noexcept] QWindow::~QWindow()

Destroys the window.

[slot] void QWindow::alert(int msec)

Causes an alert to be shown for msec milliseconds. If msec is 0 (the default), then the alert is shown indefinitely until the window becomes active again. This function has no effect on an active window.

In alert state, the window indicates that it demands attention, for example by flashing or bouncing the taskbar entry.

QSize QWindow::baseSize() const

Returns the base size of the window.

See also setBaseSize().

[slot] bool QWindow::close()

Close the window.

This closes the window, effectively calling destroy(), and potentially quitting the application. Returns true on success, false if it has a parent window (in which case the top level window should be closed instead).

See also destroy(), QGuiApplication::quitOnLastWindowClosed(), and closeEvent().

[virtual protected] void QWindow::closeEvent(QCloseEvent *ev)

Override this to handle close events (ev).

The function is called when the window is requested to close. Call QEvent::ignore() on the event if you want to prevent the window from being closed.

See also close().

void QWindow::create()

Allocates the platform resources associated with the window.

It is at this point that the surface format set using setFormat() gets resolved into an actual native surface. However, the window remains hidden until setVisible() is called.

Note that it is not usually necessary to call this function directly, as it will be implicitly called by show(), setVisible(), winId(), and other functions that require access to the platform resources.

Call destroy() to free the platform resources if necessary.

See also destroy().

QCursor QWindow::cursor() const

the cursor shape for this window

See also setCursor() and unsetCursor().

void QWindow::destroy()

Releases the native platform resources associated with this window.

See also create().

qreal QWindow::devicePixelRatio() const

Returns the ratio between physical pixels and device-independent pixels for the window. This value is dependent on the screen the window is on, and may change when the window is moved.

Common values are 1.0 on normal displays and 2.0 on Apple "retina" displays.

See also QScreen::devicePixelRatio().

[override virtual protected] bool QWindow::event(QEvent *ev)

Reimplements: QObject::event(QEvent *e).

Override this to handle any event (ev) sent to the window. Return true if the event was recognized and processed.

Remember to call the base class version if you wish for mouse events, key events, resize events, etc to be dispatched as usual.

[virtual protected] void QWindow::exposeEvent(QExposeEvent *ev)

The expose event (ev) is sent by the window system when a window moves between the un-exposed and exposed states.

An exposed window is potentially visible to the user. If the window is moved off screen, is made totally obscured by another window, is minimized, or similar, this function might be called and the value of isExposed() might change to false. You may use this event to limit expensive operations such as animations to only run when the window is exposed.

This event should not be used to paint. To handle painting implement paintEvent() instead.

A resize event will always be sent before the expose event the first time a window is shown.

See also paintEvent() and isExposed().

QString QWindow::filePath() const

the file name this window is representing.

See also setFilePath().

[virtual protected] void QWindow::focusInEvent(QFocusEvent *ev)

Override this to handle focus in events (ev).

Focus in events are sent when the window receives keyboard focus.

See also focusOutEvent().

[virtual] QObject *QWindow::focusObject() const

Returns the QObject that will be the final receiver of events tied focus, such as key events.

[signal] void QWindow::focusObjectChanged(QObject *object)

This signal is emitted when the final receiver of events tied to focus is changed to object.

See also focusObject().

[virtual protected] void QWindow::focusOutEvent(QFocusEvent *ev)

Override this to handle focus out events (ev).

Focus out events are sent when the window loses keyboard focus.

See also focusInEvent().

[override virtual] QSurfaceFormat QWindow::format() const

Reimplements: QSurface::format() const.

Returns the actual format of this window.

After the window has been created, this function will return the actual surface format of the window. It might differ from the requested format if the requested format could not be fulfilled by the platform. It might also be a superset, for example certain buffer sizes may be larger than requested.

See also setFormat(), create(), requestedFormat(), and QOpenGLContext::format().

QRect QWindow::frameGeometry() const

Returns the geometry of the window, including its window frame.

The geometry is in relation to the virtualGeometry() of its screen.

See also geometry() and frameMargins().

QMargins QWindow::frameMargins() const

Returns the window frame margins surrounding the window.

See also geometry() and frameGeometry().

QPoint QWindow::framePosition() const

Returns the top left position of the window, including its window frame.

This returns the same value as frameGeometry().topLeft().

See also setFramePosition(), geometry(), and frameGeometry().

[static] QWindow *QWindow::fromWinId(WId id)

Creates a local representation of a window created by another process or by using native libraries below Qt.

Given the handle id to a native window, this method creates a QWindow object which can be used to represent the window when invoking methods like setParent() and setTransientParent().

This can be used, on platforms which support it, to embed a QWindow inside a native window, or to embed a native window inside a QWindow.

If foreign windows are not supported or embedding the native window failed in the platform plugin, this function returns nullptr.

See also setParent().

QRect QWindow::geometry() const

Returns the geometry of the window, excluding its window frame.

The geometry is in relation to the virtualGeometry() of its screen.

See also setGeometry(), frameMargins(), and frameGeometry().

[slot] void QWindow::hide()

Hides the window.

Equivalent to calling setVisible(false).

See also show() and setVisible().

[virtual protected] void QWindow::hideEvent(QHideEvent *ev)

Override this to handle hide events (ev).

The function is called when the window has requested being hidden in the windowing system.

QIcon QWindow::icon() const

Returns the window's icon in the windowing system

See also setIcon().

bool QWindow::isActive() const

Returns true if the window is active.

This is the case for the window that has input focus as well as windows that are in the same parent / transient parent chain as the focus window.

Typically active windows should appear active from a style perspective.

To get the window that currently has focus, use QGuiApplication::focusWindow().

See also requestActivate().

bool QWindow::isAncestorOf(const QWindow *child, QWindow::AncestorMode mode = IncludeTransients) const

Returns true if the window is an ancestor of the given child. If mode is IncludeTransients, then transient parents are also considered ancestors.

bool QWindow::isExposed() const

Returns if this window is exposed in the windowing system.

When the window is not exposed, it is shown by the application but it is still not showing in the windowing system, so the application should minimize animations and other graphical activities.

An exposeEvent() is sent every time this value changes.

See also exposeEvent().

bool QWindow::isModal() const

Returns whether the window is modal.

A modal window prevents other windows from getting any input.

See also QWindow::modality.

bool QWindow::isTopLevel() const

Returns whether the window is top level, i.e. has no parent window.

[virtual protected] void QWindow::keyPressEvent(QKeyEvent *ev)

Override this to handle key press events (ev).

See also keyReleaseEvent().

[virtual protected] void QWindow::keyReleaseEvent(QKeyEvent *ev)

Override this to handle key release events (ev).

See also keyPressEvent().

[slot] void QWindow::lower()

Lower the window in the windowing system.

Requests that the window be lowered to appear below other windows.

[since 6.0] QPointF QWindow::mapFromGlobal(const QPointF &pos) const

Translates the global screen coordinate pos to window coordinates.

This function was introduced in Qt 6.0.

See also mapToGlobal().

QPoint QWindow::mapFromGlobal(const QPoint &pos) const

This is an overloaded function.

[since 6.0] QPointF QWindow::mapToGlobal(const QPointF &pos) const

Translates the window coordinate pos to global screen coordinates. For example, mapToGlobal(QPointF(0,0)) would give the global coordinates of the top-left pixel of the window.

This function was introduced in Qt 6.0.

See also mapFromGlobal().

QPoint QWindow::mapToGlobal(const QPoint &pos) const

This is an overloaded function.

QRegion QWindow::mask() const

Returns the mask set on the window.

The mask is a hint to the windowing system that the application does not want to receive mouse or touch input outside the given region.

See also setMask().

QSize QWindow::maximumSize() const

Returns the maximum size of the window.

See also setMaximumSize().

QSize QWindow::minimumSize() const

Returns the minimum size of the window.

See also setMinimumSize().

[signal] void QWindow::modalityChanged(Qt::WindowModality modality)

This signal is emitted when the Qwindow::modality property changes to modality.

[virtual protected] void QWindow::mouseDoubleClickEvent(QMouseEvent *ev)

Override this to handle mouse double click events (ev).

See also mousePressEvent() and QStyleHints::mouseDoubleClickInterval().

[virtual protected] void QWindow::mouseMoveEvent(QMouseEvent *ev)

Override this to handle mouse move events (ev).

[virtual protected] void QWindow::mousePressEvent(QMouseEvent *ev)

Override this to handle mouse press events (ev).

See also mouseReleaseEvent().

[virtual protected] void QWindow::mouseReleaseEvent(QMouseEvent *ev)

Override this to handle mouse release events (ev).

See also mousePressEvent().

[virtual protected] void QWindow::moveEvent(QMoveEvent *ev)

Override this to handle window move events (ev).

[virtual protected] bool QWindow::nativeEvent(const QByteArray &eventType, void *message, qintptr *result)

Override this to handle platform dependent events. Will be given eventType, message and result.

This might make your application non-portable.

Should return true only if the event was handled.

[virtual protected, since 6.0] void QWindow::paintEvent(QPaintEvent *ev)

The paint event (ev) is sent by the window system whenever an area of the window needs a repaint, for example when initially showing the window, or due to parts of the window being uncovered by moving another window.

The application is expected to render into the window in response to the paint event, regardless of the exposed state of the window. For example, a paint event may be sent before the window is exposed, to prepare it for showing to the user.

This function was introduced in Qt 6.0.

See also exposeEvent().

QWindow *QWindow::parent(QWindow::AncestorMode mode = ExcludeTransients) const

Returns the parent window, if any.

If mode is IncludeTransients, then the transient parent is returned if there is no parent.

A window without a parent is known as a top level window.

See also setParent().

QPoint QWindow::position() const

Returns the position of the window on the desktop excluding any window frame

See also setPosition().

[slot] void QWindow::raise()

Raise the window in the windowing system.

Requests that the window be raised to appear above other windows.

[slot] void QWindow::requestActivate()

Requests the window to be activated, i.e. receive keyboard focus.

See also isActive() and QGuiApplication::focusWindow().

[slot] void QWindow::requestUpdate()

Schedules a QEvent::UpdateRequest event to be delivered to this window.

The event is delivered in sync with the display vsync on platforms where this is possible. Otherwise, the event is delivered after a delay of at most 5 ms. If the window's associated screen reports a refresh rate higher than 60 Hz, the interval is scaled down to a value smaller than 5. The additional time is there to give the event loop a bit of idle time to gather system events, and can be overridden using the QT_QPA_UPDATE_IDLE_TIME environment variable.

When driving animations, this function should be called once after drawing has completed. Calling this function multiple times will result in a single event being delivered to the window.

Subclasses of QWindow should reimplement event(), intercept the event and call the application's rendering code, then call the base class implementation.

QSurfaceFormat QWindow::requestedFormat() const

Returns the requested surface format of this window.

If the requested format was not supported by the platform implementation, the requestedFormat will differ from the actual window format.

This is the value set with setFormat().

See also setFormat() and format().

void QWindow::resize(const QSize &newSize)

set the size of the window, excluding any window frame, to newSize

See also size() and geometry().

void QWindow::resize(int w, int h)

set the size of the window, excluding any window frame, to a QSize constructed from width w and height h

For interactively resizing windows, see startSystemResize().

See also size() and geometry().

[virtual protected] void QWindow::resizeEvent(QResizeEvent *ev)

Override this to handle resize events (ev).

The resize event is called whenever the window is resized in the windowing system, either directly through the windowing system acknowledging a setGeometry() or resize() request, or indirectly through the user resizing the window manually.

QScreen *QWindow::screen() const

Returns the screen on which the window is shown, or null if there is none.

For child windows, this returns the screen of the corresponding top level window.

See also setScreen() and QScreen::virtualSiblings().

[signal] void QWindow::screenChanged(QScreen *screen)

This signal is emitted when a window's screen changes, either by being set explicitly with setScreen(), or automatically when the window's screen is removed.

void QWindow::setBaseSize(const QSize &size)

Sets the base size of the window.

The base size is used to calculate a proper window size if the window defines sizeIncrement().

See also setMinimumSize(), setMaximumSize(), setSizeIncrement(), and baseSize().

void QWindow::setCursor(const QCursor &cursor)

set the cursor shape for this window

The mouse cursor will assume this shape when it is over this window, unless an override cursor is set. See the list of predefined cursor objects for a range of useful shapes.

If no cursor has been set, or after a call to unsetCursor(), the parent window's cursor is used.

By default, the cursor has the Qt::ArrowCursor shape.

Some underlying window implementations will reset the cursor if it leaves a window even if the mouse is grabbed. If you want to have a cursor set for all windows, even when outside the window, consider QGuiApplication::setOverrideCursor().

See also cursor() and QGuiApplication::setOverrideCursor().

void QWindow::setFilePath(const QString &filePath)

set the file name this window is representing.

The windowing system might use filePath to display the path of the document this window is representing in the tile bar.

See also filePath().

void QWindow::setFlag(Qt::WindowType flag, bool on = true)

Sets the window flag flag on this window if on is true; otherwise clears the flag.

See also setFlags(), flags(), and type().

void QWindow::setFormat(const QSurfaceFormat &format)

Sets the window's surface format.

The format determines properties such as color depth, alpha, depth and stencil buffer size, etc. For example, to give a window a transparent background (provided that the window system supports compositing, and provided that other content in the window does not make it opaque again):

QSurfaceFormat format;
format.setAlphaBufferSize(8);
window.setFormat(format);

The surface format will be resolved in the create() function. Calling this function after create() has been called will not re-resolve the surface format of the native surface.

When the format is not explicitly set via this function, the format returned by QSurfaceFormat::defaultFormat() will be used. This means that when having multiple windows, individual calls to this function can be replaced by one single call to QSurfaceFormat::setDefaultFormat() before creating the first window.

See also format(), create(), destroy(), and QSurfaceFormat::setDefaultFormat().

void QWindow::setFramePosition(const QPoint &point)

Sets the upper left position of the window (point) including its window frame.

The position is in relation to the virtualGeometry() of its screen.

See also framePosition(), setGeometry(), and frameGeometry().

[slot] void QWindow::setGeometry(const QRect &rect)

Sets the geometry of the window, excluding its window frame, to rect.

The geometry is in relation to the virtualGeometry() of its screen.

See also geometry().

[slot] void QWindow::setGeometry(int posx, int posy, int w, int h)

Sets the geometry of the window, excluding its window frame, to a rectangle constructed from posx, posy, w and h.

The geometry is in relation to the virtualGeometry() of its screen.

See also geometry().

void QWindow::setIcon(const QIcon &icon)

Sets the window's icon in the windowing system

The window icon might be used by the windowing system for example to decorate the window, and/or in the task switcher.

See also icon() and setFilePath().

bool QWindow::setKeyboardGrabEnabled(bool grab)

Sets whether keyboard grab should be enabled or not (grab).

If the return value is true, the window receives all key events until setKeyboardGrabEnabled(false) is called; other windows get no key events at all. Mouse events are not affected. Use setMouseGrabEnabled() if you want to grab that.

See also setMouseGrabEnabled().

void QWindow::setMask(const QRegion &region)

Sets the mask of the window.

The mask is a hint to the windowing system that the application does not want to receive mouse or touch input outside the given region.

The window manager may or may not choose to display any areas of the window not included in the mask, thus it is the application's responsibility to clear to transparent the areas that are not part of the mask.

See also mask().

void QWindow::setMaximumSize(const QSize &size)

Sets the maximum size of the window.

This is a hint to the window manager to prevent resizing above the specified size.

See also setMinimumSize() and maximumSize().

void QWindow::setMinimumSize(const QSize &size)

Sets the minimum size of the window.

This is a hint to the window manager to prevent resizing below the specified size.

See also setMaximumSize() and minimumSize().

bool QWindow::setMouseGrabEnabled(bool grab)

Sets whether mouse grab should be enabled or not (grab).

If the return value is true, the window receives all mouse events until setMouseGrabEnabled(false) is called; other windows get no mouse events at all. Keyboard events are not affected. Use setKeyboardGrabEnabled() if you want to grab that.

See also setKeyboardGrabEnabled().

void QWindow::setParent(QWindow *parent)

Sets the parent Window. This will lead to the windowing system managing the clip of the window, so it will be clipped to the parent window.

Setting parent to be nullptr will make the window become a top level window.

If parent is a window created by fromWinId(), then the current window will be embedded inside parent, if the platform supports it.

See also parent().

void QWindow::setPosition(const QPoint &pt)

set the position of the window on the desktop to pt

The position is in relation to the virtualGeometry() of its screen.

For interactively moving windows, see startSystemMove(). For interactively resizing windows, see startSystemResize().

See also position() and startSystemMove().

void QWindow::setPosition(int posx, int posy)

set the position of the window on the desktop to posx, posy

The position is in relation to the virtualGeometry() of its screen.

See also position().

void QWindow::setScreen(QScreen *newScreen)

Sets the screen on which the window should be shown.

If the window has been created, it will be recreated on the newScreen.

This function only works for top level windows.

See also screen() and QScreen::virtualSiblings().

void QWindow::setSizeIncrement(const QSize &size)

Sets the size increment (size) of the window.

When the user resizes the window, the size will move in steps of sizeIncrement().width() pixels horizontally and sizeIncrement().height() pixels vertically, with baseSize() as the basis.

By default, this property contains a size with zero width and height.

The windowing system might not support size increments.

See also sizeIncrement(), setBaseSize(), setMinimumSize(), and setMaximumSize().

void QWindow::setSurfaceType(QSurface::SurfaceType surfaceType)

Sets the surfaceType of the window.

Specifies whether the window is meant for raster rendering with QBackingStore, or OpenGL rendering with QOpenGLContext.

The surfaceType will be used when the native surface is created in the create() function. Calling this function after the native surface has been created requires calling destroy() and create() to release the old native surface and create a new one.

See also surfaceType(), QBackingStore, QOpenGLContext, create(), and destroy().

void QWindow::setVulkanInstance(QVulkanInstance *instance)

Associates this window with the specified Vulkan instance.

instance must stay valid as long as this QWindow instance exists.

See also vulkanInstance().

void QWindow::setWindowState(Qt::WindowState state)

set the screen-occupation state of the window

The window state represents whether the window appears in the windowing system as maximized, minimized, fullscreen, or normal.

The enum value Qt::WindowActive is not an accepted parameter.

See also windowState(), showNormal(), showFullScreen(), showMinimized(), showMaximized(), and setWindowStates().

void QWindow::setWindowStates(Qt::WindowStates state)

set the screen-occupation state of the window

The window state represents whether the window appears in the windowing system as maximized, minimized and/or fullscreen.

The window can be in a combination of several states. For example, if the window is both minimized and maximized, the window will appear minimized, but clicking on the task bar entry will restore it to the maximized state.

The enum value Qt::WindowActive should not be set.

See also windowStates(), showNormal(), showFullScreen(), showMinimized(), and showMaximized().

[slot] void QWindow::show()

Shows the window.

For child windows, this is equivalent to calling showNormal(). Otherwise, it is equivalent to calling showFullScreen(), showMaximized(), or showNormal(), depending on the platform's default behavior for the window type and flags.

See also showFullScreen(), showMaximized(), showNormal(), hide(), QStyleHints::showIsFullScreen(), and flags().

[virtual protected] void QWindow::showEvent(QShowEvent *ev)

Override this to handle show events (ev).

The function is called when the window has requested becoming visible.

If the window is successfully shown by the windowing system, this will be followed by a resize and an expose event.

[slot] void QWindow::showFullScreen()

Shows the window as fullscreen.

Equivalent to calling setWindowStates(Qt::WindowFullScreen) and then setVisible(true).

See the QWidget::showFullScreen() documentation for platform-specific considerations and limitations.

See also setWindowStates() and setVisible().

[slot] void QWindow::showMaximized()

Shows the window as maximized.

Equivalent to calling setWindowStates(Qt::WindowMaximized) and then setVisible(true).

See also setWindowStates() and setVisible().

[slot] void QWindow::showMinimized()

Shows the window as minimized.

Equivalent to calling setWindowStates(Qt::WindowMinimized) and then setVisible(true).

See also setWindowStates() and setVisible().

[slot] void QWindow::showNormal()

Shows the window as normal, i.e. neither maximized, minimized, nor fullscreen.

Equivalent to calling setWindowStates(Qt::WindowNoState) and then setVisible(true).

See also setWindowStates() and setVisible().

[override virtual] QSize QWindow::size() const

Reimplements: QSurface::size() const.

Returns the size of the window excluding any window frame

See also resize().

QSize QWindow::sizeIncrement() const

Returns the size increment of the window.

See also setSizeIncrement().

[slot] bool QWindow::startSystemMove()

Start a system-specific move operation

Calling this will start an interactive move operation on the window by platforms that support it. The actual behavior may vary depending on the platform. Usually, it will make the window follow the mouse cursor until a mouse button is released.

On platforms that support it, this method of moving windows is preferred over setPosition, because it allows a more native look-and-feel of moving windows, e.g. letting the window manager snap this window against other windows, or special tiling or resizing behavior with animations when dragged to the edge of the screen. Furthermore, on some platforms such as Wayland, setPosition is not supported, so this is the only way the application can influence its position.

Returns true if the operation was supported by the system.

[slot] bool QWindow::startSystemResize(Qt::Edges edges)

Start a system-specific resize operation

Calling this will start an interactive resize operation on the window by platforms that support it. The actual behavior may vary depending on the platform. Usually, it will make the window resize so that its edge follows the mouse cursor.

On platforms that support it, this method of resizing windows is preferred over setGeometry, because it allows a more native look and feel of resizing windows, e.g. letting the window manager snap this window against other windows, or special resizing behavior with animations when dragged to the edge of the screen.

edges should either be a single edge, or two adjacent edges (a corner). Other values are not allowed.

Returns true if the operation was supported by the system.

[override virtual] QSurface::SurfaceType QWindow::surfaceType() const

Reimplements: QSurface::surfaceType() const.

Returns the surface type of the window.

See also setSurfaceType().

[virtual protected] void QWindow::tabletEvent(QTabletEvent *ev)

Override this to handle tablet press, move, and release events (ev).

Proximity enter and leave events are not sent to windows, they are delivered to the application instance.

[virtual protected] void QWindow::touchEvent(QTouchEvent *ev)

Override this to handle touch events (ev).

Qt::WindowType QWindow::type() const

Returns the type of the window.

This returns the part of the window flags that represents whether the window is a dialog, tooltip, popup, regular window, etc.

See also flags() and setFlags().

void QWindow::unsetCursor()

Restores the default arrow cursor for this window.

QVulkanInstance *QWindow::vulkanInstance() const

Returns the associated Vulkan instance if any was set, otherwise nullptr.

See also setVulkanInstance().

[virtual protected] void QWindow::wheelEvent(QWheelEvent *ev)

Override this to handle mouse wheel or other wheel events (ev).

WId QWindow::winId() const

Returns the window's platform id.

For platforms where this id might be useful, the value returned will uniquely represent the window inside the corresponding screen.

See also screen().

Qt::WindowState QWindow::windowState() const

the screen-occupation state of the window

See also setWindowState() and windowStates().

[signal] void QWindow::windowStateChanged(Qt::WindowState windowState)

This signal is emitted when the windowState changes, either by being set explicitly with setWindowStates(), or automatically when the user clicks one of the titlebar buttons or by other means.

Qt::WindowStates QWindow::windowStates() const

the screen-occupation state of the window

The window can be in a combination of several states. For example, if the window is both minimized and maximized, the window will appear minimized, but clicking on the task bar entry will restore it to the maximized state.

See also setWindowStates().