From 2ccafcb1d891ed0fff4cc85729ca1faf5b7f1c96 Mon Sep 17 00:00:00 2001
From: Sine Striker <trueful@163.com>
Date: 周二, 19 12月 2023 17:59:15 +0800
Subject: [PATCH] Add private warnings and change pictures

---
 README.md |  161 +++++++++++++++++++++++++++++++++++++++++------------
 1 files changed, 123 insertions(+), 38 deletions(-)

diff --git a/README.md b/README.md
index 760f6f0..e3a1290 100644
--- a/README.md
+++ b/README.md
@@ -2,40 +2,53 @@
 
 Cross-platform window customization framework for Qt Widgets and Qt Quick. Support Windows, macOS, Linux.
 
-This project inherited most of [wangwenx190 FramelessHelper](https://github.com/wangwenx190/framelesshelper) implementation, with a complete refactoring and upgrading of the architecture.
+This project inherited most of [wangwenx190 FramelessHelper](https://github.com/wangwenx190/framelesshelper)
+implementation, with a complete refactoring and upgrading of the architecture.
+
+## Gallery
+
+### Basic
+
+|            Windows 10             |              MacOS              |               Linux               |
+|:---------------------------------:|:-------------------------------:|:---------------------------------:|
+| ![image](./docs/images/win10.png) | ![image](./docs/images/mac.png) | ![image](./docs/images/linux.png) |
+
+### Windows 11 Snap Layout
+
+![image](./docs/images/win11.png)
 
 ## TODO
 
-+ Fix 5.15 window unsupported behavior
++ Fix 5.15 window abnormal behavior
 + Fix window 10 top border color in dark background
 + Fix `isFixedSize` code
 + Support customized system button area on Mac
-+ Make Linux system move/resize more robust
-+ Fix unhandled WinIdChange when adding a QWebEngineView as sub-widget (Win32 and Qt fixed)
++ Implement Mac window context hook
++ Support window attribute switching on Windows
 
 ## Supported Platforms
 
-+ Microsoft Windows (Vista ~ 11)
-+ Apple Mac OSX (11+)
-+ GNU/Linux (Tested on Ubuntu)
++ Microsoft Windows
++ Apple macOS (11+)
++ GNU/Linux
 
 ## Requirements
 
-| Component | Requirement |               Detailed               |
-|:---------:|:-----------:|:------------------------------------:|
-|    Qt     |   \>=5.15   |      Core, Gui, Widgets, Quick       |
-| Compiler  |  \>=C++17   |        MSVC 2019, GCC, Clang         |
-|   CMake   |   \>=3.17   |        >=3.20 is recommended         |
+| Component | Requirement |          Details          |
+|:---------:|:-----------:|:-------------------------:|
+|    Qt     |   \>=5.15   | Core, Gui, Widgets, Quick |
+| Compiler  |  \>=C++17   |   MSVC 2019, GCC, Clang   |
+|   CMake   |   \>=3.17   |   >=3.20 is recommended   |
 
 ### Tested Compilers
 
 + Windows
-  + MSVC: 2019, 2022
-  + MinGW: 13.2.0
-+ MacOSX
-  + Clang 14.0.3
+    + MSVC: 2019, 2022
+    + MinGW (GCC): 13.2.0
++ macOS
+    + Clang 14.0.3
 + Ubuntu
-  + GCC: 9.4.0
+    + GCC: 9.4.0
 
 ## Dependencies
 
@@ -56,24 +69,27 @@
 cmake --build build --target install --config Release
 ```
 
-You can also include this directory as a sub-project if you choose CMake as your build system.
+You can also include this directory as a subproject if you choose CMake as your build system.
 
-For other build systems, you need to install with CMake first and include the corresponding configuration files in your project.
+For other build systems, you need to install with CMake first and include the corresponding configuration files in your
+project.
 
 ### Import
 
 #### CMake Project
 
-```cmake
+```sh
 cmake -B build -DQWindowKit_DIR=/path/install/cmake/QWindowKit
 ```
+
 ```cmake
 find_package(QWindowKit REQUIRED)
-taraget_link_libraries(widgets_app PUBLIC QWindowKit::Widgets)
-taraget_link_libraries(quick_app PUBLIC QWindowKit::Quick)
+target_link_libraries(widgets_app PUBLIC QWindowKit::Widgets)
+target_link_libraries(quick_app PUBLIC QWindowKit::Quick)
 ```
 
 #### QMake Project
+
 ```cmake
 # WidgetsApp.pro
 include("/path/install/share/QWindowKit/qmake/QWKWidgets.pri")
@@ -88,38 +104,107 @@
 
 ## Quick Start
 
-### Initialization
+### Qt Widgets Application
 
-First of all, you're supposed to add the following code in your `main` function in a very early stage (MUST before the construction of any `Q(Gui|Core)Application` objects).
+First, setup `WidgetWindowAgent` for your top `QWidget` instance. (Each window needs its own agent.)
 
 ```c++
-int main(int argc, char *argv[]) {
-#ifdef Q_OS_WINDOWS
-    QCoreApplication::setAttribute(Qt::AA_DontCreateNativeWidgetSiblings);
-#elif defined(Q_OS_MAC)
-# if QT_VERSION < QT_VERSION_CHECK(6, 0, 0)
-    qputenv("QT_MAC_WANTS_LAYER", "1");
-# endif
-#endif
+#include <QWKWidgets/widgetwindowagent.h>
+
+MyWidget::MyWidget(QWidget *parent) {
+    // ...
+    auto agent = new QWK::WidgetWindowAgent(w);
+    agent->setup(w);
+    // ...
 }
 ```
 
-### Qt Widgets Application
+You can also initialize the agent after the window constructs.
 
-TODO
+```c++
+auto w = new MyWidget();
+auto agent = new QWK::WidgetWindowAgent(w);
+agent->setup(w);
+```
+
+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.
+
+You can use the [`WindowBar`](examples/shared/widgetframe/windowbar.h) provided by `WidgetFrame` in the examples as the
+container of your title bar components.
+
+Let `WidgetWindowAgent` know which widget the title bar is.
+
+```c++
+agent->setTitleBarWidget(myTitleBar);
+```
+
+Set system button hints to let `WidgetWindowAgent` know the role of the child widgets, which is important for the Snap
+Layout to work.
+
+```c++
+agent->setSystemButton(QWK::WindowAgent::Base::Maximize, maxButton);
+```
+
+Set hit-test visible hint to let `WidgetWindowAgent` know the widgets that desire to receive mouse events.
+
+```c++
+agent->setHitTestVisible(myTitleBar->menuBar(), true);
+```
+
+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.
 
 ### Qt Quick Application
 
-TODO
+Make sure you have registered QWK into QtQuick:
+
+```cpp
+// ...
+#include <QWKQuick/qwkquickglobal.h>
+// ...
+
+int main(int argc, char *argv[])
+{
+    // ...
+    QQmlApplicationEngine engine;
+    // ...
+    QWK::registerTypes(&engine);
+    // ...
+}
+```
+
+Then you can use QWK data types and classes by importing it's URI:
+
+```qml
+import QtQuick 2.15
+import QtQuick.Window 2.15
+import QWindowKit 1.0
+
+Window {
+    id: window
+    visible: false // We hide it first, so we can move the window to our desired position silently.
+    Component.onCompleted: {
+        windowAgent.setup(window)
+        window.visible = true
+    }
+    WindowAgent {
+      // ...
+    }
+}
+```
+
+You can omit the version number or use "auto" instead of "1.0" for the module URI if you are using Qt6.
 
 ### Learn More
 
-See [examples](examples) for more demo use cases. The examples has no High DPI support.
+See [examples](examples) for more demo use cases. The examples have no High DPI support.
 
-## Documentatons
+## Documentations
 
 + Examples (TODO)
-+ [Framelesshelper Related](docs/framelesshelper-related.md)
++ [FramelessHelper Related](docs/framelesshelper-related.md)
 
 ## License
 

--
Gitblit v1.9.1