Update document

Sine Striker

2023-12-23 087591ff0090d0417dfda10968a0411caab4a7c0

Update document

 README.md

@@ -114,6 +114,8 @@

### Qt Widgets Application

#### Setup Window Agent

First, setup `WidgetWindowAgent` for your top `QWidget` instance. (Each window needs its own agent.)

```c++
@@ -134,6 +136,8 @@
auto agent = new QWK::WidgetWindowAgent(w);
agent->setup(w);
```

#### Construct Title bar

Then, construct your title bar widget, without which the window lacks the basic interaction feature, and it's better to put it into the window's layout.

@@ -165,9 +169,20 @@

The rest region within the title bar will be regarded as the draggable area for the user to move the window.

Check [`MainWindow`](examples/mainwindow/mainwindow.cpp#L108) example to get detailed information.

#### Window Attributes (Experimental)

On Windows 11, you can use this API to enable system effects.

```c++
agent->setWindowAttribute("mica", true);
```

Available keys: `mica`, `mica-alt`, `acrylic`, `dark-mode`.

### Qt Quick Application

#### Initialization

Make sure you have registered `QWindowKit` into QtQuick:

@@ -183,6 +198,8 @@
    // ...
}
```

#### Setup Window Components

Then you can use `QWindowKit` data types and classes by importing it's URI:

@@ -206,6 +223,10 @@

You can omit the version number or use "auto" instead of "1.0" for the module URI if you are using Qt6.

#### Window Attributes (Experimental)

TODO

### Learn More

See [examples](examples) for more demo use cases. The examples have no High DPI support.

 src/core/contexts/win32windowcontext.cpp

@@ -715,12 +715,18 @@
        auto hWnd = reinterpret_cast<HWND>(winId);

#if QWINDOWKIT_CONFIG(ENABLE_WINDOWS_SYSTEM_BORDER)
        if (!isWin10OrGreater())
#endif
        {
        if (!isWin10OrGreater()) {
            static constexpr const MARGINS margins = {1, 1, 1, 1};
            DynamicApis::instance().pDwmExtendFrameIntoClientArea(hWnd, &margins);
        }
#else
        {
            static const MARGINS margins =
                isWin10OrGreater() ? MARGINS{0, 0, 0, 0} : MARGINS{1, 1, 1, 1};
            DynamicApis::instance().pDwmExtendFrameIntoClientArea(hWnd, &margins);
        }
#endif


        {
            auto style = ::GetWindowLongPtrW(hWnd, GWL_STYLE);
@@ -852,52 +858,53 @@
            }
            return true;
        } else if (key == QStringLiteral("acrylic-material")) {
            if (!isWin10OrGreater()) {
            if (!isWin11OrGreater()) {
                return false;
            }
            if (attribute.userType() == QMetaType::QColor) {
            if (attribute.toBool()) {
                // We need to extend the window frame into the whole client area to be able
                // to see the blurred window background.
                apis.pDwmExtendFrameIntoClientArea(hwnd, &extendMargins);
                if (isWin11OrGreater()) {

                    const _DWM_SYSTEMBACKDROP_TYPE backdropType = _DWMSBT_TRANSIENTWINDOW;
                    apis.pDwmSetWindowAttribute(hwnd, _DWMWA_SYSTEMBACKDROP_TYPE, &backdropType,
                                                sizeof(backdropType));
                } else {
                    auto gradientColor = attribute.value<QColor>();

                    ACCENT_POLICY policy{};
                    policy.dwAccentState = ACCENT_ENABLE_ACRYLICBLURBEHIND;
                    policy.dwAccentFlags = ACCENT_ENABLE_ACRYLIC_WITH_LUMINOSITY;
                    // This API expects the #AABBGGRR format.
                    policy.dwGradientColor =
                        DWORD(qRgba(gradientColor.blue(), gradientColor.green(),
                                    gradientColor.red(), gradientColor.alpha()));
                    WINDOWCOMPOSITIONATTRIBDATA wcad{};
                    wcad.Attrib = WCA_ACCENT_POLICY;
                    wcad.pvData = &policy;
                    wcad.cbData = sizeof(policy);
                    apis.pSetWindowCompositionAttribute(hwnd, &wcad);
                }
                // PRIVATE API REFERENCE:
                //     QColor gradientColor = {};
                //     ACCENT_POLICY policy{};
                //     policy.dwAccentState = ACCENT_ENABLE_ACRYLICBLURBEHIND;
                //     policy.dwAccentFlags = ACCENT_ENABLE_ACRYLIC_WITH_LUMINOSITY;
                //     // This API expects the #AABBGGRR format.
                //     policy.dwGradientColor =
                //         DWORD(qRgba(gradientColor.blue(), gradientColor.green(),
                //                     gradientColor.red(), gradientColor.alpha()));
                //     WINDOWCOMPOSITIONATTRIBDATA wcad{};
                //     wcad.Attrib = WCA_ACCENT_POLICY;
                //     wcad.pvData = &policy;
                //     wcad.cbData = sizeof(policy);
                //     apis.pSetWindowCompositionAttribute(hwnd, &wcad);
            } else {
                if (isWin11OrGreater()) {
                    const _DWM_SYSTEMBACKDROP_TYPE backdropType = _DWMSBT_AUTO;
                    apis.pDwmSetWindowAttribute(hwnd, _DWMWA_SYSTEMBACKDROP_TYPE, &backdropType,
                                                sizeof(backdropType));
                } else {
                    ACCENT_POLICY policy{};
                    policy.dwAccentState = ACCENT_DISABLED;
                    policy.dwAccentFlags = ACCENT_NONE;
                    WINDOWCOMPOSITIONATTRIBDATA wcad{};
                    wcad.Attrib = WCA_ACCENT_POLICY;
                    wcad.pvData = &policy;
                    wcad.cbData = sizeof(policy);
                    apis.pSetWindowCompositionAttribute(hwnd, &wcad);
                }

                // PRIVATE API REFERENCE:
                //     ACCENT_POLICY policy{};
                //     policy.dwAccentState = ACCENT_DISABLED;
                //     policy.dwAccentFlags = ACCENT_NONE;
                //     WINDOWCOMPOSITIONATTRIBDATA wcad{};
                //     wcad.Attrib = WCA_ACCENT_POLICY;
                //     wcad.pvData = &policy;
                //     wcad.cbData = sizeof(policy);
                //     apis.pSetWindowCompositionAttribute(hwnd, &wcad);

                apis.pDwmExtendFrameIntoClientArea(hwnd, &defaultMargins);
            }
            return true;
        } else if (key == QStringLiteral("dwm-blur")) {
            // TODO: Optimize
            // Currently not available!!!
            if (attribute.toBool()) {
                // We need to extend the window frame into the whole client area to be able
                // to see the blurred window background.