[unix] Rewrite documentation for update_window_focus_state

platforms/unix/src/adapter.rs

@@ -162,7 +162,48 @@ impl Adapter {
         }
     }
 
-    /// Update the tree state based on whether the window is focused.
+    /// Notifies the adapter that the window is active.
+    ///
+    /// # Discussion
+    ///
+    /// The correct use of this function is critical to make your application accessible on Linux.
+    ///
+    /// Linux's orca screen reader will not read your accessibility tree unless:
+    ///
+    /// 1.  An immediate child of the root object is in the ATSPI active state
+    /// 2.  No two children report the active state with "too much" temporal overlap, including
+    ///     across applications.
+    ///
+    /// Note that there is **no warning or diagnostic in accesskit or platform accessibility inspectors to alert
+    /// you to these problems, but your software won't work with the screen reader**.
+    ///
+    /// ## The ATSPI active state
+    ///
+    /// `accesskit` only reports the ATSPI active state for the [accesskit::Role::Window] role.
+    /// Accordingly, this is the only practical choice for the [accesskit::Tree] `root` field.  Use
+    /// of another role in this position is sometimes seen on Linux but not supported by accesskit.
+    ///
+    /// accesskit reports the ATSPI active state only after this function is called with `true`.
+    ///
+    /// ## Temporal overlap
+    ///
+    /// orca gets much of its information about which window to read not from the compositor but by
+    /// the self-report of the applications via the ATSPI active state.
+    ///
+    /// Thus when two eligible children both report the active state, it is unclear which one orca
+    /// should read.  orca will retry after a short period to see if the overlap is a transient condition.
+    /// However when two children persist in reporting the active state, orca must choose one of them
+    /// to win and be read, and one to lose and to be treated as inactive regardless of its report of
+    /// active.
+    ///
+    /// Once orca concludes that the loser's active state was erroneous, this **latches until the losing
+    /// state changes**.  That is: when the winner relinquishes its active state, the loser does not
+    /// regain it.  Applications that enter this state are likely to be completely inaccessible
+    /// to screen reader users unless they call this function with `false` and `true` again.
+    ///
+    /// Wayland does not provide a portable event to indicate that a surface becomes active/inactive
+    /// such as to drive calling this function.  In practice, keyboard Enter and Leave events are
+    /// often used instead.
     pub fn update_window_focus_state(&mut self, is_focused: bool) {
         let mut state = self.state.lock().unwrap();
         match &mut *state {