From 95e2038e2013c06371bda17d9460035b4791961d Mon Sep 17 00:00:00 2001
From: cosven <yinshaowen241@gmail.com>
Date: Wed, 20 Nov 2024 23:59:00 +0800
Subject: [PATCH] [docs](gui): add some comments and docs

---
 feeluown/gui/components/avatar.py |  8 ++++++--
 feeluown/gui/provider_ui.py       | 14 ++++++++++++--
 2 files changed, 18 insertions(+), 4 deletions(-)

diff --git a/feeluown/gui/components/avatar.py b/feeluown/gui/components/avatar.py
index ee2779748d..da09d9d736 100644
--- a/feeluown/gui/components/avatar.py
+++ b/feeluown/gui/components/avatar.py
@@ -82,6 +82,9 @@ def contextMenuEvent(self, e) -> None:
         menu.exec_(e.globalPos())
 
     def on_provider_ui_login_event(self, provider_ui, event):
+        current_pvd_ui = self._app.current_pvd_ui_mgr.get()
+        if current_pvd_ui == provider_ui and event == 2:
+            return
         if event in (1, 2):
             run_afn(self.show_pvd_ui_current_user)
             run_afn(
@@ -90,12 +93,13 @@ def on_provider_ui_login_event(self, provider_ui, event):
             )
 
     def on_pvd_ui_selected(self, pvd_ui):
-        self._app.current_pvd_ui_mgr.set(pvd_ui)
         if isinstance(pvd_ui, UISupportsLoginEvent):
             pvd_ui.login_event.connect(self.on_provider_ui_login_event)
         if isinstance(pvd_ui, UISupportsLoginOrGoHome):
             pvd_ui.login_or_go_home()
-        run_afn(self.show_pvd_ui_current_user)
+        # Set current provider ui at the very last.
+        # Must not set it before handling login event.
+        self._app.current_pvd_ui_mgr.set(pvd_ui)
 
     def on_provider_selected(self, provider: ProviderUiItem):
         self._app.current_pvd_ui_mgr.set_item(provider)
diff --git a/feeluown/gui/provider_ui.py b/feeluown/gui/provider_ui.py
index e6714dd907..214f584563 100644
--- a/feeluown/gui/provider_ui.py
+++ b/feeluown/gui/provider_ui.py
@@ -23,14 +23,24 @@ class NavBtn:
 
 @runtime_checkable
 class UISupportsLoginOrGoHome(Protocol):
-
     @abstractmethod
     def login_or_go_home(self):
-        ...
+        """This method is called when the avatar is clicked.
+
+        Typically, ProviderUI can implement this method as follows:
+        - When no user is logged in, ProviderUI MAY show a login dialog.
+        - When a user is logged in, ProviderUI MAY show the homepage.
+          At the same time, ProviderUI MAY emit a login success event.
+        """
 
 
 @runtime_checkable
 class UISupportsLoginEvent(Protocol):
+    """
+    When the user is logged in, ProviderUI MAY emit a login success event.
+    This allows FeelUOwn to perform certain actions based on this event,
+    for example, fetching and show the user's playlist.
+    """
 
     @property
     @abstractmethod