From d9fa2c6082da533555c3655a4808622fa7c9fd11 Mon Sep 17 00:00:00 2001
From: ManoloFLTK <41016272+ManoloFLTK@users.noreply.github.com>
Date: Fri, 28 Jul 2023 15:27:38 +0200
Subject: Wayland.dox: add info about the xdg decoration protocol

Also, use KWin to name the KDE desktop's Wayland compositor.
---
 documentation/src/osissues.dox |  7 ++++---
 documentation/src/wayland.dox  | 17 ++++++++++++-----
 2 files changed, 16 insertions(+), 8 deletions(-)

(limited to 'documentation')

diff --git a/documentation/src/osissues.dox b/documentation/src/osissues.dox
index 998a8a54d..042d8ba31 100644
--- a/documentation/src/osissues.dox
+++ b/documentation/src/osissues.dox
@@ -1069,10 +1069,11 @@ or in <tt>$HOME/.local/share/applications/</tt> so it's available to a single us
 \subsection osissues_wayland_decoration Window titlebars
 Wayland supports both client-side window decoration (CSD), where client applications
 are responsible for drawing window titlebars, and server-side window
-decoration (SSD), where the Wayland compositor itself draws window titlebars. Among 3
+decoration (SSD), where the Wayland compositor itself draws window titlebars. Among 4
 tested Wayland compositors, Mutter (gnome's compositor) and Weston use CSD mode
-whereas the KDE compositor uses SSD mode. When running in CSD mode, FLTK uses a library called
-<a href=https://gitlab.gnome.org/jadahl/libdecor>libdecor</a> to draw titlebars.
+whereas the KWin and Sway compositors use SSD mode.
+When running in CSD mode, FLTK uses a library
+called <a href=https://gitlab.freedesktop.org/libdecor/libdecor>libdecor</a> to draw titlebars.
 The libdecor library has been conceived to use various plug-in's to draw
 titlebars in various fashions intended to match any desktop's preferred titlebar style.
 FLTK supports drawing titlebars with any libdecor plug-in via an environment variable
diff --git a/documentation/src/wayland.dox b/documentation/src/wayland.dox
index e1a921f70..16f71eb41 100644
--- a/documentation/src/wayland.dox
+++ b/documentation/src/wayland.dox
@@ -280,7 +280,7 @@ accessible from this object.
 For example, when \c interface equals "wl_compositor", the value returned by
 \c wl_registry_bind() is stored as member \c wl_compositor of the
 \c Fl_Wayland_Screen_Driver object.
-\c registry_handle_global() also identifies whether the Mutter, Weston, or KDE compositor is connected
+\c registry_handle_global() also identifies whether the Mutter, Weston, or KWin compositor is connected
 and stores this information in static member variable \c Fl_Wayland_Screen_Driver::compositor.
 
 Wayland calls \c registry_handle_global() with its parameter \c interface equals to
@@ -726,7 +726,7 @@ is unmapped by function \c Fl_Wayland_Window_Driver::hide(), the surface's list
 is emptied.
 
 <h3>Fractional scaling</h3>
-The KDE compositor, and gnome too if specially set, allow to use <em>fractional scaling</em>
+The KWin compositor, and gnome too if specially set, allow to use <em>fractional scaling</em>
 that can take intermediate values between 100% and 200%. Wayland implements this rendering all
 <tt>wl_surface</tt>'s as if the scaling was at 200%, and downsizing them
 to the desired fractional scale value at the compositing stage.
@@ -956,9 +956,16 @@ Desktop. As of early 2023, two titlebar-drawing \c libdecor plugins are availabl
 Because \c libdecor is not yet in Linux packages, or only in a preliminary state, FLTK bundles the
 most recent source code of \c libdecor and its plugins. This code is included in libfltk.
 FLTK uses \c libdecor-gtk when software package \c libgtk-3-dev is present in the
-system, and \c libdecor-cairo otherwise.
-
-\c Libdecor uses the Wayland protocol <tt>"xdg decoration unstable v1"</tt> hinted at before.
+build system, and \c libdecor-cairo otherwise.
+
+\c Libdecor uses the Wayland protocol
+<a href=https://wayland.app/protocols/xdg-decoration-unstable-v1>
+xdg decoration unstable v1</a> to request being decorated by a supporting compositor.
+If the running compositor supports SSD, \c libdecor doesn't draw window titlebars because
+the compositor does it. That is what happens with the \c KWin and \c Sway compositors.
+However, if environment variable \c LIBDECOR_FORCE_CSD is defined to value \c 1 when an
+FLTK app runs, \c libdecor instructs an SSD-able compositor to refrain from decorating its
+windows and decorates windows itself.
 
 CMake \c OPTION_USE_SYSTEM_LIBDECOR has been defined to allow FLTK in the future, when \c libdecor and
 \c libdecor-gtk will be part of Linux packages, to use these packages rather than the \c libdecor
-- 
cgit v1.2.3