From 89f29fa12ecba247ba4f7c02f9cf609ae58bf505 Mon Sep 17 00:00:00 2001
From: patrick96 <p.ziegler96@gmail.com>
Date: Thu, 23 Mar 2023 22:38:42 +0100
Subject: [PATCH] tray: documentation

---
 include/x11/tray_client.hpp |  7 +++++--
 src/x11/tray_client.cpp     | 17 ++++++++++++++---
 src/x11/tray_manager.cpp    | 19 ++-----------------
 3 files changed, 21 insertions(+), 22 deletions(-)

diff --git a/include/x11/tray_client.hpp b/include/x11/tray_client.hpp
index 8da59ed1..2d0dfb9a 100644
--- a/include/x11/tray_client.hpp
+++ b/include/x11/tray_client.hpp
@@ -106,6 +106,11 @@ class client : public non_copyable_mixin, public non_movable_mixin {
    */
   xembed::info m_xembed{};
 
+  /**
+   * Background pixmap of wrapper window
+   */
+  xcb_pixmap_t m_pixmap{XCB_NONE};
+
   /**
    * Whether the wrapper window is currently mapped.
    */
@@ -124,8 +129,6 @@ class client : public non_copyable_mixin, public non_movable_mixin {
   shared_ptr<bg_slice> m_bg_slice;
   unique_ptr<cairo::context> m_context;
   unique_ptr<cairo::xcb_surface> m_surface;
-
-  xcb_pixmap_t m_pixmap{XCB_NONE};
 };
 
 } // namespace tray
diff --git a/src/x11/tray_client.cpp b/src/x11/tray_client.cpp
index 3a253dc1..18438eba 100644
--- a/src/x11/tray_client.cpp
+++ b/src/x11/tray_client.cpp
@@ -3,19 +3,28 @@
 #include <xcb/xcb.h>
 #include <xcb/xcb_aux.h>
 #include <xcb/xcb_icccm.h>
-#include "xpp/pixmap.hpp"
 
 #include "utils/memory.hpp"
 #include "x11/connection.hpp"
 #include "x11/ewmh.hpp"
 #include "x11/winspec.hpp"
+#include "xpp/pixmap.hpp"
 
 POLYBAR_NS
 
 namespace tray {
 
 /*
- * TODO proper background of wrapper window
+ * The client window is embedded into a wrapper window with identical, size, depth, and visual.
+ * This wrapper window is used to paint the background of the icon (also dealing with transparent backgrounds through
+ * pseudo-transparency).
+ *
+ * True transprency is currently not supported here because it cannot be achieved with external compositors (those only
+ * seem to work for top-level windows) and has to be implemented by hand.
+ *
+ * TODO proper background of wrapper window:
+ *
+ * (TODO: Check if this is still necessary, the current approach seems to work)
  *
  * Do first possible:
  *
@@ -342,11 +351,13 @@ void client::update_bg() const {
   m_log.trace("%s: Update background", name());
 
   // Composite background slice with background color.
-  // TODO this doesn't have to be done if the background color is not transparent.
+
   m_context->clear();
 
   auto root_bg = m_bg_slice->get_surface();
   if (root_bg != nullptr) {
+    // TODO the compositing doesn't have to be done if the background color is not transparent.
+    // In that case, the bg slice can be completely skipped, we shouldn't event observe the background
     *m_context << CAIRO_OPERATOR_SOURCE << *root_bg;
     m_context->paint();
     *m_context << CAIRO_OPERATOR_OVER;
diff --git a/src/x11/tray_manager.cpp b/src/x11/tray_manager.cpp
index 2f00af4b..b7b0dbf0 100644
--- a/src/x11/tray_manager.cpp
+++ b/src/x11/tray_manager.cpp
@@ -27,28 +27,13 @@
  *
  * Ref: https://specifications.freedesktop.org/systemtray-spec/systemtray-spec-latest.html
  *
- * This class manages embedded tray icons by placing them on the bar in the correct position; the position itself is
+ * This class manages embedded tray icons by placing them on the bar in the correct positions; the start position is
  * requested by the renderer.
  *
  * The tray manager needs to trigger bar updates only when the size of the entire tray changes (e.g. when tray icons are
- * added/removed). EVerything else can be handled without an update.
+ * added/removed). Everything else can be handled without an update.
  */
 
-// ====================================================================================================
-//
-// TODO: 32-bit visual
-//
-// _NET_SYSTEM_TRAY_VISUAL visual_id VISUALID/32
-//
-// The property should be set by the tray manager to indicate the preferred visual for icon windows.
-//
-// To avoid ambiguity about the colormap to use this visual must either be the default visual for
-// the screen or it must be a TrueColor visual. If this property is set to a visual with an alpha
-// channel, the tray manager must use the Composite extension to composite the icon against the
-// background using PictOpOver.
-//
-// ====================================================================================================
-
 POLYBAR_NS
 
 namespace tray {