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

---
 src/widgets/widgetwindowagent.cpp |   67 +++++++++++++++++++++++++++++----
 1 files changed, 59 insertions(+), 8 deletions(-)

diff --git a/src/widgets/widgetwindowagent.cpp b/src/widgets/widgetwindowagent.cpp
index af15481..e2b6db1 100644
--- a/src/widgets/widgetwindowagent.cpp
+++ b/src/widgets/widgetwindowagent.cpp
@@ -9,6 +9,14 @@
 
 namespace QWK {
 
+    /*!
+        \class WidgetWindowAgent
+        \brief WindowAgentBase is the window agent for QtWidgets.
+
+        It provides interfaces for QtWidgets and processes some Qt events related to the QWidget
+        instance.
+    */
+
     WidgetWindowAgentPrivate::WidgetWindowAgentPrivate() = default;
 
     WidgetWindowAgentPrivate::~WidgetWindowAgentPrivate() = default;
@@ -16,12 +24,22 @@
     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) {
     }
 
+    /*!
+        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) {
@@ -36,38 +54,47 @@
         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;
         }
-#ifdef Q_OS_MACOS
-        d->setupMacOSTitleBar(w);
-#endif
-        Q_EMIT titleBarWidgetChanged(w);
+        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,18 +103,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);
     }
 
+    /*!
+        \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