From 51f08dfe1c93d699b8f3f71a3f079c338a28555e Mon Sep 17 00:00:00 2001
From: ManoloFLTK <41016272+ManoloFLTK@users.noreply.github.com>
Date: Sat, 18 Feb 2023 08:41:30 +0100
Subject: More detailed documentation of Wayland custom cursors

---
 documentation/src/wayland.dox | 33 ++++++++++++++++++---------------
 1 file changed, 18 insertions(+), 15 deletions(-)

(limited to 'documentation/src')

diff --git a/documentation/src/wayland.dox b/documentation/src/wayland.dox
index 14f8c0f99..331d8d79b 100644
--- a/documentation/src/wayland.dox
+++ b/documentation/src/wayland.dox
@@ -521,10 +521,9 @@ Finally, function do_set_cursor() of file \c Fl_Wayland_Screen_Driver.cxx makes
 the current \c wl_cursor object to draw its shape on screen. That's done with a call to
 \c wl_pointer_set_cursor() and a few other functions.
 
-Function <tt>Fl_Wayland_Window_Driver::set_cursor(const Fl_RGB_Image *rgb, int hotx, int hoty)</tt>
-is used to create a custom cursor shape. This operation uses a non-public type,
-<tt>struct cursor_image</tt>, defined for FLTK in file \c Fl_Wayland_Window_Driver.cxx as copied from
-file \c wayland-cursor.c of the Wayland project source code:
+<h3>Custom cursor shapes</h3>
+To support custom cursors, FLTK presently uses a <u>non-public type</u>,
+<tt>struct cursor_image</tt>, defined in file \c Fl_Wayland_Window_Driver.cxx as follows:
 \code
 struct cursor_image {
   struct wl_cursor_image image;
@@ -533,12 +532,17 @@ struct cursor_image {
   int offset;
 };
 \endcode
-This definition shows that a pointer to a \c cursor_image object can also be viewed as a pointer to the
+This definition has been copied to the FLTK source code from file \c wayland-cursor.c of the
+Wayland project source code because it's not accessible via Wayland header files.
+It shows that a pointer to a \c cursor_image object can also be viewed as a pointer to the
 embedded <tt>struct wl_cursor_image</tt> object, this one being part of the public Wayland API.
 It also shows that a <tt>struct cursor_image</tt> object has an associated
-<tt>struct wl_buffer</tt> object used to contain the cursor's graphics. Function \c set_cursor()
-creates a \c cursor_image object, allocates the corresponding \c wl_buffer by a call to
-\c create_shm_buffer() and draws into that buffer the cursor's shape using regular FLTK means.
+<tt>struct wl_buffer</tt> object used to contain the cursor's graphics.
+
+Function <tt>Fl_Wayland_Window_Driver::set_cursor(const Fl_RGB_Image *rgb, int hotx, int hoty)</tt>
+gives FLTK support of custom cursor shapes. It creates a \c cursor_image object, allocates the
+corresponding \c wl_buffer by a call to \c Fl_Wayland_Graphics_Driver::create_shm_buffer() and draws
+the cursor shape into that buffer using the offscreen-drawing method of FLTK.
 
 The public type <tt>struct wl_cursor</tt> is essentially an array of \c wl_cursor_image objects
 and a name:
@@ -549,16 +553,15 @@ struct wl_cursor {
   char *name;
 };
 \endcode
-Function \c set_cursor() also creates a <tt>struct wl_cursor</tt> object containing a single
-\c wl_cursor_image, which is in fact the \c cursor_image.
+Function \c set_cursor(const Fl_RGB_Image *rgb, …) also creates a <tt>struct wl_cursor</tt> object
+containing a single \c wl_cursor_image, which is in fact the \c cursor_image.
 A pointer to this <tt>struct wl_cursor</tt> object is stored in member \c custom_cursor of the
 window's \ref wld_window. Finally, function \c do_set_cursor() makes the system pointer use
-the custom \c wl_cursor to draw its shape. That is how the custom cursor shape is constructed and used.
+the custom \c wl_cursor to draw its shape.
 
-Member function
-\c Fl_Wayland_Window_Driver::delete_cursor_() is used to delete any custom cursor shape. This
-occurs when a window associated to a custom cursor is un-mapped and when such a window gets
-associated to a standard cursor or to a new custom cursor.
+Member function \c Fl_Wayland_Window_Driver::delete_cursor_() is used to delete any custom cursor
+shape. This occurs when a window associated to a custom cursor is un-mapped and when such a window
+gets associated to a standard cursor or to a new custom cursor.
 
 
 
-- 
cgit v1.2.3