Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion .gitmodules
Original file line number Diff line number Diff line change
@@ -1,4 +1,7 @@
[submodule "qmsetup"]
path = qmsetup
url = ../../stdware/qmsetup.git
branch = main
branch = main
[submodule "pyqwindowkit"]
path = pyqwindowkit
url = https://github.com/childishtree/PyQWindowKit.git
34 changes: 21 additions & 13 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,9 @@ You can share your findings, thoughts and ideas on improving / implementing QWin
- Support Mac system buttons geometry customization
- Simpler APIs, more detailed documentations and comments

## Python bindings
Use Shiboken6 to provide bindings for PySide6.

## Gallery

### Windows 11 (With Snap Layout)
Expand All @@ -38,29 +41,29 @@ You can share your findings, thoughts and ideas on improving / implementing QWin

### macOS & Linux

| macOS | Linux (Ubuntu 20.04) |
| macOS | Linux (Ubuntu 20.04) |
|:-------------------------------:|:---------------------------------:|
| ![image](./docs/images/mac.png) | ![image](./docs/images/linux.png) |

## Requirements

| Component | Requirement | Details |
| Component | Requirement | Details |
|:---------:|:-----------:|:-------------------------:|
| Qt | \>=5.12 | Core, Gui, Widgets, Quick |
| Compiler | \>=C++17 | MSVC 2019, GCC, Clang |
| CMake | \>=3.19 | >=3.20 is recommended |
| Qt | \>=5.12 | Core, Gui, Widgets, Quick |
| Compiler | \>=C++17 | MSVC 2019, GCC, Clang |
| CMake | \>=3.19 | >=3.20 is recommended |

Please read [Vulnerabilities](#Vulnerabilities) carefully to acquire detailed requirements.

### Tested Compilers

- Windows
- MSVC: 2019, 2022
- MinGW (GCC): 13.2.0
- MSVC: 2019, 2022
- MinGW (GCC): 13.2.0
- macOS
- Clang 14.0.3
- Clang 14.0.3
- Ubuntu
- GCC: 9.4.0
- GCC: 9.4.0

## Dependencies

Expand All @@ -85,6 +88,7 @@ cmake -B build -S . \
cmake --build build --target install --config Debug
cmake --build build --target install --config Release
```

Read the root `CMakeLists.txt` for more build options.

You can also include this directory as a subproject if you choose CMake as your build system.
Expand Down Expand Up @@ -133,7 +137,7 @@ The following initialization should be done before any widget constructs.
int main(int argc, char *argv[])
{
QGuiApplication::setAttribute(Qt::AA_DontCreateNativeWidgetSiblings)

// ...
}
```
Expand Down Expand Up @@ -265,27 +269,31 @@ See [examples](examples) for more demo use cases. The examples have no High DPI
- QWindowKit Internals [TODO]
- [FramelessHelper Related](docs/framelesshelper-related.md)


### Vulnerabilities

#### Qt Version

- To achieve better frameless functionality, QWindowKit depends heavily on Qt's internal implementation. However, there are many differences in different versions of Qt, and earlier versions of Qt5 and Qt6 have many bugs which make it extremely difficult for QWindowKit to workaround without changing the Qt source code.
- And also due to limited manpower, although QWindowKit can be successfully compiled on Qt 5.12 or later, it can hardly work perfectly on all Qt versions.
- Therefore, the following Qt version ranges are recommended, if there are any exceptions with QWindowKit in your application, make sure the Qt version you use is in the ranges before raising the issue.
- Qt 5: 5.15.2 or higher (you may be able to build QWK on top of older Qt versions, however, QWK may not behave well and we won't accept bug reports from these unsupported versions)
- Qt 6: 6.6.2 or higher (the newer, the better)
- Qt 5: 5.15.2 or higher (you may be able to build QWK on top of older Qt versions, however, QWK may not behave well and we won't accept bug reports from these unsupported versions)
- Qt 6: 6.6.2 or higher (the newer, the better)

#### Hot Switch

- Once you have made the window frameless, it will not be able to switch back to the system frame again unless you destroy your window and recreate it with different settings.

#### Native Child Widget

- If you are about to add a widget with `Qt::WA_NativeWindow` property enabled as a descendent of the frameless window, you should enable `Qt::WA_DontCreateNativeAncestors` of it in advance.

#### Size Constrains

- If you want to disable window resizing, you can set a fixed size, which is officially supported by QWindowKit. If you use other special means to achieve this (eg. hook Win32 messages), QWK doesn't guarantee everything can still be fully functional.
- If you set a maximized width or height, the window should not be maximized because you cannot get the correct window size through Qt APIs. You may workaround this by using system APIs such as `GetWindowRect` or `GetClientRect`. The root cause lies deep in Qt QPA implementations and currently we don't know how to fix it without modifying Qt itself.

#### Windows 10

- Due to the inherent defects in the Windows 10 window system, the top border will disappear when the system title bar is removed. We have filtered Qt's event and perfectly reshown the system top border, thanks to the implementation of Windows Terminal for our reference. However, this workaround only works with QtWidgets and QtQuick (**only when rendering through OpenGL/OpenGLES/D3D11/D3D12, not Vulkan**) applications.
- For QtQuick applications, when rendering through Vulkan, the top border will become a solid black line, that's a known issue and currently we are not able to fix it. Please use QWK's borderless version if you can't change your graphics backend.
- For QtQuick applications, when rendering through D3D11/D3D12, you may see a strange white line on window top, it may disappear if you resize the window. Currently it's a bug and we are working hard to find a suitable solution for it, for now you can set the environment variable `QT_QPA_DISABLE_REDIRECTION_SURFACE` to a non-zero value in your `main` function before any `QCoreApplication` instance is created to workaround this issue. This environment variable is first introduced in Qt 6.7.0 (qtbase/838fc606c170fac112f7bb5971c2507b7b56d08a). You must **NOT** enable this feature for OpenGL/OpenGLES/Vulkan because their rendering will be totally broken.
Expand Down
1 change: 1 addition & 0 deletions pyqwindowkit
Submodule pyqwindowkit added at 5ad809