desktop: add commentary clarifying focus rules

diff --git a/include/labwc.h b/include/labwc.h
index 0f6b2a2a5003eeb2426fb84901036440bb8b77a6..84d39d4f34d6cb1fb843fab7f340a19bcaae0305 100644 (file)
--- a/include/labwc.h
+++ b/include/labwc.h
@@ -375,6 +375,18 @@ void foreign_toplevel_update_outputs(struct view *view);
  *              cannot assume this means that the window actually has keyboard
  *              or pointer focus, in this compositor are they called together.
  */
+
+/**
+ * desktop_focus_view() - do multiple things to make a view "active" and
+ * ready to use:
+ *  - unminimize
+ *  - switch to the workspace it's on
+ *  - give input (keyboard) focus
+ *  - optionally raise above other views
+ *
+ * It's okay to call this function even if the view isn't mapped or the
+ * session is locked/input is inhibited; it will simply do nothing.
+ */
 void desktop_focus_view(struct view *view, bool raise);
 void desktop_arrange_all_views(struct server *server);
 void desktop_focus_output(struct output *output);
@@ -393,6 +405,15 @@ enum lab_cycle_dir {
  */
 struct view *desktop_cycle_view(struct server *server, struct view *start_view,
        enum lab_cycle_dir dir);
+
+/**
+ * desktop_focus_topmost_view() - focus the topmost view on the current
+ * workspace, skipping views that claim not to want focus (those can
+ * still be focused by explicit request, e.g. by clicking in them).
+ *
+ * This function is typically called when the focused view is hidden
+ * (closes, is minimized, etc.) to focus the "next" view underneath.
+ */
 void desktop_focus_topmost_view(struct server *server);
 
 void keyboard_cancel_keybind_repeat(struct keyboard *keyboard);

diff --git a/src/desktop.c b/src/desktop.c
index 41c43afad782d2ed3261b5fa0799457d32a01da8..eac5645345a418b5390e82246258143d0685de08 100644 (file)
--- a/src/desktop.c
+++ b/src/desktop.c
@@ -73,6 +73,13 @@ desktop_focus_view(struct view *view, bool raise)
                workspaces_switch_to(view->workspace, /*update_focus*/ false);
        }
 
+       /*
+        * Give input focus, even if the view claims not to want it (see
+        * view->impl->wants_focus). This is a workaround for so-called
+        * "globally active" X11 views (MATLAB known to be one such)
+        * that expect to be able to control focus themselves, but can't
+        * under labwc since it's disallowed at the wlroots level.
+        */
        struct seat *seat = &server->seat;
        if (view->surface != seat->seat->keyboard_state.focused_surface) {
                seat_focus_surface(seat, view->surface);

diff --git a/src/xwayland.c b/src/xwayland.c
index ec9fe4a2ad22d02d32421a9cd8c2e80c882e474f..265e63d977e861ad1b676801794cd005f2902b51 100644 (file)
--- a/src/xwayland.c
+++ b/src/xwayland.c
@@ -49,7 +49,8 @@ xwayland_view_wants_focus(struct view *view)
         * Clients that use XSetInputFocus() to explicitly set the input
         * focus should set the WM_TAKE_FOCUS atom in WM_PROTOCOLS.
         * Currently, labwc does not support this method of taking focus
-        * and thus makes no use of WM_TAKE_FOCUS.
+        * and thus ignores WM_TAKE_FOCUS. These views can still be
+        * focused by explicit user action (e.g. clicking in them).
         */
        return (bool)hints->input;
 }