Wayland.dox: add a few more detailed explanations

1 files changed, 45 insertions, 28 deletions

diff --git a/documentation/src/wayland.dox b/documentation/src/wayland.dox
index bbd1ae242..598d1b7fd 100644
--- a/documentation/src/wayland.dox
+++ b/documentation/src/wayland.dox
@@ -54,7 +54,7 @@ Wayland allows to create popup windows positioned relatively to a previously map
 window. This allows FLTK to position adequately menu and tooltip windows, see
 \ref menu-windows.
 
-Wayland uses a trick of its own to handle lists of linked records. It defines the opaque type
+Wayland uses a trick of its own to handle lists of linked records. It defines type
 <tt>struct wl_list</tt> and a few macros (\c wl_list_init(), \c wl_list_for_each(), \c wl_list_insert(),
 \c wl_list_for_each_safe(), \c wl_list_remove()) to manage linked lists. Records put in these
 lists must contain a member variable of type <tt>struct wl_list</tt> used to link records together
@@ -96,7 +96,8 @@ to a mapped Fl_Window.
 
 Classes \c Fl_Wayland_Window_Driver, \c Fl_Wayland_Screen_Driver, \c Fl_Wayland_Graphics_Driver,
 \c Fl_Wayland_Copy_Surface_Driver, \c Fl_Wayland_Image_Surface_Driver and
-\c Fl_Wayland_Gl_Window_Driver contain all the Wayland-specific code of the FLTK library.
+\c Fl_Wayland_Gl_Window_Driver and \c file fl_wayland_platform_init.cxx
+contain all the Wayland-specific code of the FLTK library.
 This code is located at \c src/drivers/Wayland/ in the FLTK source tree.
 A single C++ source file generally contains all the code of a given class.
 The code related to copy, paste and drag-and-drop operations, however,
@@ -111,7 +112,7 @@ The public C API to Wayland, xkb and libdecor libraries are obtained with
 #include <wayland-cursor.h>
 #include <xkbcommon/xkbcommon.h>
 #include <xkbcommon/xkbcommon-compose.h>
-#include <linux/input.h>
+#include <linux/input.h> // for BTN_LEFT, BTN_RIGHT, BTN_MIDDLE
 #include "../../../libdecor/src/libdecor.h"
 #include "../../../libdecor/src/libdecor-plugin.h"
 \endcode
@@ -142,8 +143,8 @@ use the same type name for different purposes or the same symbol name.
 That is why function <tt>fl_xid(const Fl_Window*)</tt> is deprecated in FLTK 1.4 and replaced by
 \c fl_wl_xid() for Wayland and \c fl_x11_xid() for X11. Also, global variable
 <tt>Window fl_window</tt> is not used by the Wayland platform which instead uses
-<tt>static struct wld_window *Fl_Wayland_Window_Driver:: wld_window;</tt>.
-The FLTK library contains also a dedicated source file,
+<tt>static struct wld_window *Fl_Wayland_Window_Driver:: wld_window</tt>.
+The FLTK library contains also a short source file,
 \c fl_wayland_platform_init.cxx, that determines, at startup time, whether
 the app will run as a Wayland or as an X11 client. Function \c attempt_wayland() therein performs
 this choice as follows :
@@ -180,19 +181,26 @@ corresponding Wayland object, usually right after the object's creation, by a ca
 specific Wayland function named following the form \c wl_XXX_add_listener().
 For example, this code:
 \code
+static void surface_enter(……) { …… } // called when a surface enters a display
+static void surface_leave(……) { …… } // called when a surface leaves a display
+
 static struct wl_surface_listener surface_listener = {
   surface_enter,
   surface_leave,
 };
 
-  pointer_type pter_to_data;
-  struct wl_surface *my_wl_surface;
-  my_wl_surface = wl_compositor_create_surface(scr_driver->wl_compositor);
-  wl_surface_add_listener(my_wl_surface, &surface_listener, pter_to_data);
+some_pointer_type pter_to_data;
+struct wl_surface *my_wl_surface;
+my_wl_surface = wl_compositor_create_surface(scr_driver->wl_compositor);
+wl_surface_add_listener(my_wl_surface, &surface_listener, pter_to_data);
 \endcode
-creates a Wayland object of type <tt>struct wl_surface</tt>, associates
-a 2-member listener called \c surface_listener to it,
-and associates \c pter_to_data to it as <em>user data</em>. The \c wl_surface object's
+creates a Wayland object of type <tt>struct wl_surface</tt>, and associates it with
+a 2-member listener called \c surface_listener. After this, Wayland is expected to call
+the 2 listener members, \c surface_enter or \c surface_leave, each time \c my_wl_surface will
+enter or leave, respectively, a display. The arguments of these calls, not detailed here,
+allow the member functions to identify which surface enters or leaves which display.
+The \c wl_surface_add_listener() call above also associates \c pter_to_data to
+\c my_wl_surface as <em>user data</em>. The \c wl_surface object's
 "user data" can be obtained later calling function \c wl_surface_get_user_data().
 
 Wayland function \c wl_proxy_get_listener() returns a pointer
@@ -231,19 +239,25 @@ supported by the compositor or a system feature such as displays and keyboards.
 This code allows to run the client until all calls to \c registry_handle_global() have
 occurred:
 \code
-  static const struct wl_callback_listener sync_listener = {
-    sync_done
-  };
+static void sync_done(void *data, struct wl_callback *cb, uint32_t time) {
+  *(struct wl_callback **)data = NULL;
+  wl_callback_destroy(cb);
+}
 
-  struct wl_callback *registry_cb = wl_display_sync(wl_display);
-  wl_callback_add_listener(registry_cb, &sync_listener, &registry_cb);
-  while (registry_cb) wl_display_dispatch(wl_display);
+static const struct wl_callback_listener sync_listener = {
+  sync_done
+};
+
+struct wl_callback *registry_cb = wl_display_sync(wl_display);
+wl_callback_add_listener(registry_cb, &sync_listener, &registry_cb);
+while (registry_cb) wl_display_dispatch(wl_display);
 \endcode
 A pointer to an object of type <tt>struct wl_callback</tt> created by function
 \c wl_display_sync() is assigned to variable \c registry_cb.
 Then a 1-member listener is attached to this object. Wayland will run this listener's
 member function, \c sync_done(), after all calls to \c registry_handle_global() have
-occurred. Function \c sync_done() sets to null variable \c registry_cb.
+occurred. Function \c sync_done() sets to null variable \c registry_cb and destroys
+the \c wl_callback.
 Finally, function \c wl_display_dispatch() is called as long as variable \c registry_cb is
 not null. This makes Wayland process all its pending requests until \c sync_done() runs.
 
@@ -259,8 +273,9 @@ and version of a component or feature of the Wayland system. It's necessary to c
 point to the corresponding Wayland protocol or system feature. This pointer is stored in a dedicated
 member variable of the unique \c Fl_Wayland_Screen_Driver object of an FLTK app, or of another object
 accessible from this object.
-For example, when \c interface equals "wl_compositor", \c the value returned by wl_registry_bind() is
-stored as member \c wl_compositor of the \c Fl_Wayland_Screen_Driver 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
 and stores this information in static member variable \c Fl_Wayland_Screen_Driver::compositor.
 
@@ -548,9 +563,9 @@ in function \c Fl_Wayland_Window_Driver::make_current() with
 Thus, \c buffer_commit() runs only when \c cb is NULL. If an app rapidly performs calls
 to Fl_Window::make_current() and to drawing functions, FLTK will copy \c draw_buffer to the Wayland
 buffer and instruct Wayland to map it to the display when \c cb is NULL
-which means that the compositor is ready to start performing a mapping operation, and will only
-modify \c draw_buffer when \c cb is not NULL, letting the compositor complete its ongoing
-mapping task.
+which means that the compositor is ready to start performing a mapping operation.
+In contrast, FLTK will only modify \c draw_buffer when \c cb is not NULL, letting the compositor
+complete its ongoing mapping task.
 For example, FLTK's mandelbrot test app set to fullscreen can be seen to progressively fill its window from
 top to bottom by blocks of lines, each block appearing when the compositor is ready to map
 a new buffer. When the compositor is not ready, the app does not block but continues
@@ -1019,10 +1034,12 @@ Files dropped are received one pathname per line, with no \c '\\n' after the las
 Wayland uses <a href=https://www.khronos.org/api/egl>EGL™</a> to interface OpenGL with the underlying
 native platform window system. OpenGL-using FLTK apps are therefore linked to \c libwayland-egl.so and
 \c libEGL.so in addition to \c libGL.so and \c libGLU.so. These librairies allow FLTK to
-create and initialize an EGL display connection, create objects of type \c wl_egl_window,
-\c EGLSurface, and \c GLContext. An object of type \c wl_egl_window is created by function
-\c Fl_Wayland_Gl_Window_Driver::make_current_before() in reference to
-an existing \c wl_surface object which connects this EGL-object with a given Wayland window.
+create and initialize an EGL display connection, and create objects of type \c wl_egl_window,
+\c EGLSurface, and \c GLContext.
+Function \c Fl_Wayland_Gl_Window_Driver::make_current_before() creates an object of type
+\c wl_egl_window for each show()'n \c Fl_Gl_Window calling function \c wl_egl_window_create().
+The first argument of this call of type <tt>struct wl_surface</tt> is how a Wayland window is
+set to use OpenGL.
 
 FLTK calls function \c Fl_Wayland_Gl_Window_Driver::swap_buffers() each time it wants a GL context
 to be sent to the display. This function contains some pure GL code to emulate an overlay buffer