From 1571d7b43228a0ed4347f681a16b2b23defccda9 Mon Sep 17 00:00:00 2001
From: Sine Striker <trueful@163.com>
Date: 周三, 27 12月 2023 03:52:03 +0800
Subject: [PATCH] Add doxygen documentations

---
 README.md |   89 ++++++++++++++++++++++++++++++++------------
 1 files changed, 65 insertions(+), 24 deletions(-)

diff --git a/README.md b/README.md
index 556e78b..97cf4fa 100644
--- a/README.md
+++ b/README.md
@@ -1,11 +1,15 @@
 # QWindowKit
 
-Cross-platform window customization framework for Qt Widgets and Qt Quick. Support Windows, macOS, Linux.
+Cross-platform window customization framework for Qt Widgets and Qt Quick.
 
 This project inherited most of [wangwenx190 FramelessHelper](https://github.com/wangwenx190/framelesshelper)
 implementation, with a complete refactoring and upgrading of the architecture.
 
-Support as many system native features as possible without requiring additional dependencies.
+Feature requests are welcome.
+
+## Join with Us :triangular_flag_on_post:
+
+You can join our [Discord channel](https://discord.gg/grrM4Tmesy). You can share your findings, thoughts and ideas on improving / implementing FramelessHelper functionalities on more platforms and apps!
 
 ## Supported Platforms
 
@@ -13,17 +17,26 @@
 + Apple macOS (11+)
 + GNU/Linux
 
+## Features
+
++ Full support of Windows 11 Snap Layout
++ Better workaround to handle Windows 10 top border issue
++ Support Mac system buttons geometry customization
++ Simpler APIs, more detailed documentations and comments
+
 ## Gallery
 
 ### Windows 11 (With Snap Layout)
+
 ![image](./docs/images/win11.png)
 
 ### Windows 10 (And 7, Vista)
+
 ![image](./docs/images/win10.png)
 
-### MacOS & Linux
+### macOS & Linux
 
-|              MacOS              |       Linux (Ubuntu 20.04)        |
+|              macOS              |       Linux (Ubuntu 20.04)        |
 |:-------------------------------:|:---------------------------------:|
 | ![image](./docs/images/mac.png) | ![image](./docs/images/linux.png) |
 
@@ -31,7 +44,7 @@
 
 | Component | Requirement |          Details          |
 |:---------:|:-----------:|:-------------------------:|
-|    Qt     |   \>=5.15   | Core, Gui, Widgets, Quick |
+|    Qt     |   \>=5.12   | Core, Gui, Widgets, Quick |
 | Compiler  |  \>=C++17   |   MSVC 2019, GCC, Clang   |
 |   CMake   |   \>=3.17   |   >=3.20 is recommended   |
 
@@ -47,7 +60,7 @@
 
 ## Dependencies
 
-+ Qt 5.15 or higher
++ Qt 5.12 or higher
 + [qmsetup](https://github.com/stdware/qmsetup)
 
 ## Integrate
@@ -101,6 +114,8 @@
 
 ### Qt Widgets Application
 
+#### Setup Window Agent
+
 First, setup `WidgetWindowAgent` for your top `QWidget` instance. (Each window needs its own agent.)
 
 ```c++
@@ -108,13 +123,14 @@
 
 MyWidget::MyWidget(QWidget *parent) {
     // ...
-    auto agent = new QWK::WidgetWindowAgent(w);
-    agent->setup(w);
+    auto agent = new QWK::WidgetWindowAgent(this);
+    agent->setup(this);
     // ...
 }
 ```
 
-You can also initialize the agent after the window constructs.
+If you don't want to derive a new widget class or change the constructor, you can initialize the agent after the window
+constructs.
 
 ```c++
 auto w = new MyWidget();
@@ -122,17 +138,22 @@
 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.
+#### Construct Title bar
 
-You can use the [`WindowBar`](examples/shared/widgetframe/windowbar.h) provided by `WidgetFrame` in the examples as the container of your title bar components.
+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);
+agent->setTitleBar(myTitleBar);
 ```
 
-Set system button hints to let `WidgetWindowAgent` know the role of the child widgets, which is important for the Snap Layout to work.
+Next, 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::WindowAgentBase::WindowIcon, myTitleBar->iconButton());
@@ -141,7 +162,13 @@
 agent->setSystemButton(QWK::WindowAgentBase::Close, myTitleBar->closeButton());
 ```
 
-Set hit-test visible hint to let `WidgetWindowAgent` know the widgets that desire to receive mouse events.
+Doing this does not mean that these buttons' click events are automatically associated with window actions, you still
+need to manually connect the signals and slots to emulate the native window behaviors.
+
+On macOS, this step can be skipped because it is better to use the buttons provided by the system.
+
+Last but not least, set hit-test visible hint to let `WidgetWindowAgent` know other widgets that desire to receive mouse
+events.
 
 ```c++
 agent->setHitTestVisible(myTitleBar->menuBar(), true);
@@ -149,11 +176,21 @@
 
 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
 
-Make sure you have registered QWK into QtQuick:
+#### Initialization
+
+Make sure you have registered `QWindowKit` into QtQuick:
 
 ```cpp
 #include <QWKQuick/qwkquickglobal.h>
@@ -167,6 +204,8 @@
     // ...
 }
 ```
+
+#### Setup Window Components
 
 Then you can use `QWindowKit` data types and classes by importing it's URI:
 
@@ -194,19 +233,21 @@
 
 See [examples](examples) for more demo use cases. The examples have no High DPI support.
 
-## Documentations
-
-+ Examples (TODO)
 + [FramelessHelper Related](docs/framelesshelper-related.md)
 
 ## TODO
 
 + 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
-+ Implement Mac window context hook
-+ Support window attribute switching on Windows
++ Support Mac style change notification
++ Support Mac system buttons customization for Quick
++ More documentations
++ When do we support Linux native features?
+
+## Special Thanks
+
++ [Arabaku](https://github.com/Arabaku)
++ [Maplespe](https://github.com/Maplespe)
++ [zhiyiYo](https://github.com/zhiyiYo)
 
 ## License
 

--
Gitblit v1.9.1