From d905187230c893bd387656278f57c60ffe6f2507 Mon Sep 17 00:00:00 2001
From: Sine Striker <trueful@163.com>
Date: 周三, 27 12月 2023 21:07:42 +0800
Subject: [PATCH] minor tweaks

---
 src/widgets/widgetwindowagent.cpp |   81 ++++++++++++++++++++++++++++++++--------
 1 files changed, 65 insertions(+), 16 deletions(-)

diff --git a/src/widgets/widgetwindowagent.cpp b/src/widgets/widgetwindowagent.cpp
index ff76aef..d78219f 100644
--- a/src/widgets/widgetwindowagent.cpp
+++ b/src/widgets/widgetwindowagent.cpp
@@ -9,22 +9,37 @@
 
 namespace QWK {
 
-    WidgetWindowAgentPrivate::WidgetWindowAgentPrivate() {
-    }
+    /*!
+        \class WidgetWindowAgent
+        \brief WindowAgentBase is the window agent for QtWidgets.
 
-    WidgetWindowAgentPrivate::~WidgetWindowAgentPrivate() {
-    }
+        It provides interfaces for QtWidgets and processes some Qt events related to the QWidget
+        instance.
+    */
+
+    WidgetWindowAgentPrivate::WidgetWindowAgentPrivate() = default;
+
+    WidgetWindowAgentPrivate::~WidgetWindowAgentPrivate() = default;
 
     void WidgetWindowAgentPrivate::init() {
     }
 
+    /*!
+        Constructs a widget agent, it's better to set the widget to setup as \a parent.
+    */
     WidgetWindowAgent::WidgetWindowAgent(QObject *parent)
         : WidgetWindowAgent(*new WidgetWindowAgentPrivate(), parent) {
     }
 
-    WidgetWindowAgent::~WidgetWindowAgent() {
-    }
+    /*!
+        Destructor.
+    */
+    WidgetWindowAgent::~WidgetWindowAgent() = default;
 
+    /*!
+        Installs the window agent on the widget. The window agent will take over some of the window
+        events, making the window look frameless.
+    */
     bool WidgetWindowAgent::setup(QWidget *w) {
         Q_ASSERT(w);
         if (!w) {
@@ -39,35 +54,50 @@
         w->setAttribute(Qt::WA_DontCreateNativeAncestors);
         w->setAttribute(Qt::WA_NativeWindow);
 
-        if (!d->setup(w, new WidgetItemDelegate())) {
-            return false;
-        }
+        d->setup(w, new WidgetItemDelegate());
         d->hostWidget = w;
 
-#ifdef Q_OS_WINDOWS
+#if defined(Q_OS_WINDOWS) && QWINDOWKIT_CONFIG(ENABLE_WINDOWS_SYSTEM_BORDERS)
         d->setupWindows10BorderWorkaround();
 #endif
         return true;
     }
 
+    /*!
+        Returns the title bar widget.
+    */
     QWidget *WidgetWindowAgent::titleBar() const {
         Q_D(const WidgetWindowAgent);
         return static_cast<QWidget *>(d->context->titleBar());
     }
 
+    /*!
+        Sets the title bar widget, all system button and hit-test visible widget references that
+        have been set will be removed.
+    */
     void WidgetWindowAgent::setTitleBar(QWidget *w) {
         Q_D(WidgetWindowAgent);
         if (!d->context->setTitleBar(w)) {
             return;
         }
-        Q_EMIT titleBarWidgetChanged(w);
+#ifdef Q_OS_MAC
+        setSystemButtonArea(nullptr);
+#endif
+        Q_EMIT titleBarChanged(w);
     }
 
+    /*!
+        Returns the system button of the given type.
+    */
     QWidget *WidgetWindowAgent::systemButton(SystemButton button) const {
         Q_D(const WidgetWindowAgent);
         return static_cast<QWidget *>(d->context->systemButton(button));
     }
 
+    /*!
+        Sets the system button of the given type, the system buttons always receive mouse events so
+        you don't need to call \c setHitTestVisible for them.
+    */
     void WidgetWindowAgent::setSystemButton(SystemButton button, QWidget *w) {
         Q_D(WidgetWindowAgent);
         if (!d->context->setSystemButton(button, w)) {
@@ -76,23 +106,42 @@
         Q_EMIT systemButtonChanged(button, w);
     }
 
+    /*!
+        Returns \a true if the widget can receive mouse events on title bar.
+    */
     bool WidgetWindowAgent::isHitTestVisible(const QWidget *w) const {
         Q_D(const WidgetWindowAgent);
         return d->context->isHitTestVisible(w);
     }
 
+    /*!
+        Makes the widget able to receive mouse events on title bar if \a visible is \c true.
+        You're supposed to make sure that the specified widget \a w is a child or descendant
+        of the title bar widget.
+    */
     void WidgetWindowAgent::setHitTestVisible(const QWidget *w, bool visible) {
         Q_D(WidgetWindowAgent);
         d->context->setHitTestVisible(w, visible);
     }
 
-    void WidgetWindowAgent::setHitTestVisible(const QRect &rect, bool visible) {
-        Q_D(WidgetWindowAgent);
-        d->context->setHitTestVisible(rect, visible);
-    }
-
+    /*!
+        \internal
+    */
     WidgetWindowAgent::WidgetWindowAgent(WidgetWindowAgentPrivate &d, QObject *parent)
         : WindowAgentBase(d, parent) {
         d.init();
     }
+
+    /*!
+        \fn void WidgetWindowAgent::titleBarChanged(const QWidget *w)
+
+        This signal is emitted when the title bar widget is replaced.
+    */
+
+    /*!
+        \fn void WidgetWindowAgent::systemButtonChanged(SystemButton button, const QWidget *w)
+
+        This signal is emitted when a system button is replaced.
+    */
+
 }

--
Gitblit v1.9.1