Cursor configuration

[MoD]

I noticed the other day that the documentation on cursor theming under Wayland is pretty confusing and was unable to gather a clear idea of how users are supposed to configure cursor sizes and themes from the documents I read. Here's what I encountered.

man weston states:
> "[Weston] has also its own X window manager where cursor themes and sizes can be chosen using XCURSOR_PATH and XCURSOR_SIZE environment variables."
This only really states anything about XWayland, and it is true that XWayland itself obeys XCURSOR_SIZE, falling back to 32 if it is unset, and uses  XcursorLibraryLoadImages to load the cursor, which obeys XCURSOR_PATH. This documentation is fine, though it's not very clear whether the same configuration methods may be assumed for Weston itself or not.

man weston also states:
> "XCURSOR_PATH: Set the list of paths to look for cursors in. It changes both libwayland-cursor and libXcursor, so it affects both Wayland and X11 based clients."
This is also fine; libwayland-cursor and libXCursor do indeed both honor this environment variable. I'm just noting this for completeness.

man weston, again:
> "XCURSOR_SIZE: This variable can be set for choosing an specific size of cursor. Affect (sic) Wayland and X11 clients."
This is true for XWayland, which will fall back to a size of 32 if the size is not set, but toytoolkit hard-codes 32 in window.c and never reads XCURSOR_SIZE. GTK hard-codes 32 in gdkcursor-wayland.c. libwayland-cursor itself does not read XCURSOR_SIZE and, as far as I can tell has no way to request a 'default' size, hence the hard-coded 32 fallbacks.

Cursor theme configuration is also confusing:
Toytoolkit reads the weston shell configuration key "cursor-theme" to determine the theme to load, whereas XWayland passes NULL to use the default (configured via ~/.icons/default/cursors) theme. GTK reads the "gtk-cursor-theme-name" setting from its configuration, falling back to "default" if it is unset.

My presumption is that users prefer to have consistent cursor sizing, paths, and themes between applications. To make this more feasible, at the very least all toolkits need to be able to share a size and cursor path; users /may/ prefer to theme cursors differently for different toolkits, as is possible under X11. The cursor path is fine, though it seems somewhat strange to use 'XCURSOR_PATH' rather than 'WL_CURSOR_PATH' or such (for historical compatibility with libXcursor, I guess). There seems to be no standardization of cursor size configuration, and those toolkits that do not have their own setting for it all hard-code 32.

If XCURSOR_PATH is to be the standard, then is XCURSOR_SIZE also intended to be used universally by Wayland clients? Should individual toolkits read it, or should libwayland-cursor be changed to allow to request a default cursor size (read from XCURSOR_SIZE with 32 as a fallback)? The latter seems preferable since it centralizes code that should perform the same behavior, but I'm not sure if the libwayland-cursor API is set in stone. If/when these two environment variables are (or should be) universally supported, they should be clearly documented as such in weston's man page.

Thoughts?

MoD