Qt for Windows - Specific Issues

This page contains information about Qt for Windows.

Installation location

Installing Qt into a directory with spaces, for example, C:\Program Files, may cause issues with qmake.

Install Qt into a sub-directory without spaces to avoid this problem.

Maximum path length

The Win32 API that both Qt and compiler tools use has a built-in maximum file path length of 260 characters (MAX_PATH). This can hit you in various forms if either your absolute or relative directory structures are too verbose. It is therefore recommended to keep the file system paths within limits, and put build directories nearby the source directories.

Visual Studio

If you are experiencing strange problems with using special flags that modify the alignment of structure and union members (such as /Zp2) then you will need to recompile Qt with the flags set for the application as well.

Fullscreen OpenGL Based Windows

When a window is using an OpenGL based surface and is appearing in full screen mode, problems can occur with other top-level windows which are part of the application. Due to limitations of the Windows DWM, compositing is not handled correctly for OpenGL based windows when going into full screen mode. As a result, other top-level windows are not placed on top of the full screen window when they are made visible. For example, menus may not appear correctly, or dialogs fail to show up.

A window can use an OpenGL based surface either explicitly when setSurfaceType() is called, or when something that requires OpenGL is used inside the window, causing the whole window to be OpenGL based. For example, QOpenGLWidget or QQuickWidget can trigger this. However, if the surface is contained in a QWindow which is hosted with createWindowContainer(), or the obsoleted QGLWidget is used and it does cover the entire full screen window, then this problem does not occur.

To solve this problem, native APIs can be used to enable the WS_BORDER attribute when showing in full screen mode. This can be utilized as follows:

bool Widget::event(QEvent *e) {
#if defined(Q_OS_WIN)
    if (e->type() == QEvent::WinIdChange) {
        if (windowHandle()) {
            HWND handle = reinterpret_cast<HWND>(windowHandle()->winId());
            SetWindowLongPtr(handle, GWL_STYLE, GetWindowLongPtr(handle, GWL_STYLE) | WS_BORDER);
        }
    }
#endif
    return QWidget::event(e);
}

This will give the full screen window a 1-pixel border, thus enabling the other top level windows to appear on top.