add a convenient API

Yuhang Zhao

2023-12-19 f9aa4aacae56e3a82bce492196ff1802f3ecaf02

 README.md

@@ -1,8 +1,16 @@
# QWindowKit

Cross-platform window customization framework for Qt Widgets and Qt Quick.
Cross-platform window customization framework for Qt Widgets and Qt Quick. Support Windows, macOS, Linux.

This project inherited most of [FramelessHelper](https://github.com/wangwenx190/framelesshelper)'s 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.

## 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
+ Make Linux system move/resize more robust

## Supported Platforms

@@ -30,6 +38,7 @@

## Dependencies

+ Qt 5.15 or higher
+ [qmsetup](https://github.com/stdware/qmsetup)

## Integrate
@@ -46,7 +55,7 @@
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.

@@ -54,13 +63,13 @@

#### 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
@@ -78,25 +87,48 @@

## 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 WidgetWindowAgent(w);
    agent->setup(w);
    // ...
}
```

### Qt Widgets Application
You can also initialize the agent after the window constructs.
```c++
auto w = new MyWidget();
auto agent = new WidgetWindowAgent(w);
agent->setup(w);
```

TODO
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

@@ -104,13 +136,13 @@

### Learn More

See [examples](examples) for more demo use cases.
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

QWindowKit is licensed under the [Apache 2.0 License](LICENSE).
QWindowKit is licensed under the Apache 2.0 License.