feat: Live regions on macOS (#196)

Author: mwcampbell

platforms/macos/src/appkit/accessibility_constants.rs

@@ -3,7 +3,7 @@
 // the LICENSE-APACHE file) or the MIT license (found in
 // the LICENSE-MIT file), at your option.
 
-use objc2::foundation::NSString;
+use objc2::foundation::{NSInteger, NSString};
 
 #[link(name = "AppKit", kind = "framework")]
 extern "C" {
@@ -13,6 +13,7 @@ extern "C" {
     pub(crate) static NSAccessibilityTitleChangedNotification: &'static NSString;
     pub(crate) static NSAccessibilityValueChangedNotification: &'static NSString;
     pub(crate) static NSAccessibilitySelectedTextChangedNotification: &'static NSString;
+    pub(crate) static NSAccessibilityAnnouncementRequestedNotification: &'static NSString;
 
     // Roles
     pub(crate) static NSAccessibilityButtonRole: &'static NSString;
@@ -46,4 +47,12 @@ extern "C" {
     pub(crate) static NSAccessibilityTextFieldRole: &'static NSString;
     pub(crate) static NSAccessibilityToolbarRole: &'static NSString;
     pub(crate) static NSAccessibilityUnknownRole: &'static NSString;
+
+    // Notification user info keys
+    pub(crate) static NSAccessibilityAnnouncementKey: &'static NSString;
+    pub(crate) static NSAccessibilityPriorityKey: &'static NSString;
 }
+
+// Announcement priorities
+pub(crate) const NSAccessibilityPriorityMedium: NSInteger = 50;
+pub(crate) const NSAccessibilityPriorityHigh: NSInteger = 90;

platforms/macos/src/appkit/accessibility_functions.rs

@@ -3,9 +3,14 @@
 // the LICENSE-APACHE file) or the MIT license (found in
 // the LICENSE-MIT file), at your option.
 
-use objc2::foundation::{NSObject, NSString};
+use objc2::foundation::{NSDictionary, NSObject, NSString};
 
 #[link(name = "AppKit", kind = "framework")]
 extern "C" {
     pub(crate) fn NSAccessibilityPostNotification(element: &NSObject, notification: &NSString);
+    pub(crate) fn NSAccessibilityPostNotificationWithUserInfo(
+        element: &NSObject,
+        notification: &NSString,
+        user_info: &NSDictionary<NSString, NSObject>,
+    );
 }

platforms/macos/src/appkit/mod.rs

@@ -3,6 +3,8 @@
 // the LICENSE-APACHE file) or the MIT license (found in
 // the LICENSE-MIT file), at your option.
 
+#![allow(non_upper_case_globals)]
+
 #[link(name = "AppKit", kind = "framework")]
 extern "C" {}
 

platforms/macos/src/event.rs

@@ -3,17 +3,29 @@
 // the LICENSE-APACHE file) or the MIT license (found in
 // the LICENSE-MIT file), at your option.
 
-use accesskit::NodeId;
+use accesskit::{Live, NodeId};
 use accesskit_consumer::{DetachedNode, FilterResult, Node, TreeChangeHandler, TreeState};
-use objc2::foundation::NSString;
+use objc2::{
+    foundation::{NSInteger, NSMutableDictionary, NSNumber, NSObject, NSString},
+    msg_send, Message,
+};
 use std::rc::Rc;
 
 use crate::{
     appkit::*,
     context::Context,
-    node::{filter, NodeWrapper},
+    node::{filter, filter_detached, NodeWrapper},
 };
 
+// Workaround for https://github.com/madsmtm/objc2/issues/306
+fn set_object_for_key<K: Message, V: Message>(
+    dictionary: &mut NSMutableDictionary<K, V>,
+    value: &V,
+    key: &K,
+) {
+    let _: () = unsafe { msg_send![dictionary, setObject: value, forKey: key] };
+}
+
 // This type is designed to be safe to create on a non-main thread
 // and send to the main thread. This ability isn't yet used though.
 pub(crate) enum QueuedEvent {
@@ -22,9 +34,24 @@ pub(crate) enum QueuedEvent {
         notification: &'static NSString,
     },
     NodeDestroyed(NodeId),
+    Announcement {
+        text: String,
+        priority: NSInteger,
+    },
 }
 
 impl QueuedEvent {
+    fn live_region_announcement(node: &Node) -> Self {
+        Self::Announcement {
+            text: node.name().unwrap(),
+            priority: if node.live() == Live::Assertive {
+                NSAccessibilityPriorityHigh
+            } else {
+                NSAccessibilityPriorityMedium
+            },
+        }
+    }
+
     fn raise(self, context: &Rc<Context>) {
         match self {
             Self::Generic {
@@ -44,6 +71,39 @@ impl QueuedEvent {
                     };
                 }
             }
+            Self::Announcement { text, priority } => {
+                let view = match context.view.load() {
+                    Some(view) => view,
+                    None => {
+                        return;
+                    }
+                };
+
+                let window = match view.window() {
+                    Some(window) => window,
+                    None => {
+                        return;
+                    }
+                };
+
+                let mut user_info = NSMutableDictionary::<_, NSObject>::new();
+                let text = NSString::from_str(&text);
+                set_object_for_key(&mut user_info, &*text, unsafe {
+                    NSAccessibilityAnnouncementKey
+                });
+                let priority = NSNumber::new_isize(priority);
+                set_object_for_key(&mut user_info, &*priority, unsafe {
+                    NSAccessibilityPriorityKey
+                });
+
+                unsafe {
+                    NSAccessibilityPostNotificationWithUserInfo(
+                        &window,
+                        NSAccessibilityAnnouncementRequestedNotification,
+                        &user_info,
+                    )
+                };
+            }
         }
     }
 }
@@ -91,8 +151,14 @@ impl EventGenerator {
 }
 
 impl TreeChangeHandler for EventGenerator {
-    fn node_added(&mut self, _node: &Node) {
-        // TODO: text changes, live regions
+    fn node_added(&mut self, node: &Node) {
+        if filter(node) != FilterResult::Include {
+            return;
+        }
+        if node.name().is_some() && node.live() != Live::Off {
+            self.events
+                .push(QueuedEvent::live_region_announcement(node));
+        }
     }
 
     fn node_updated(&mut self, old_node: &DetachedNode, new_node: &Node) {
@@ -124,6 +190,15 @@ impl TreeChangeHandler for EventGenerator {
                 notification: unsafe { NSAccessibilitySelectedTextChangedNotification },
             });
         }
+        if new_node.name().is_some()
+            && new_node.live() != Live::Off
+            && (new_node.name() != old_node.name()
+                || new_node.live() != old_node.live()
+                || filter_detached(old_node) != FilterResult::Include)
+        {
+            self.events
+                .push(QueuedEvent::live_region_announcement(new_node));
+        }
     }
 
     fn focus_moved(&mut self, _old_node: Option<&DetachedNode>, new_node: Option<&Node>) {
@@ -139,7 +214,6 @@ impl TreeChangeHandler for EventGenerator {
     }
 
     fn node_removed(&mut self, node: &DetachedNode, _current_state: &TreeState) {
-        // TODO: text changes
         self.events.push(QueuedEvent::NodeDestroyed(node.id()));
     }
 }

platforms/macos/src/node.rs

@@ -30,8 +30,8 @@ use std::{
 
 use crate::{appkit::*, context::Context, util::*};
 
-fn ns_role(node: &Node) -> &'static NSString {
-    let role = node.role();
+fn ns_role(node_state: &NodeState) -> &'static NSString {
+    let role = node_state.role();
     // TODO: Handle special cases.
     unsafe {
         match role {
@@ -54,7 +54,7 @@ fn ns_role(node: &Node) -> &'static NSString {
             Role::CheckBox => NSAccessibilityCheckBoxRole,
             Role::RadioButton => NSAccessibilityRadioButtonRole,
             Role::TextField => {
-                if node.is_multiline() {
+                if node_state.is_multiline() {
                     NSAccessibilityTextAreaRole
                 } else {
                     NSAccessibilityTextFieldRole
@@ -231,19 +231,35 @@ fn ns_role(node: &Node) -> &'static NSString {
     }
 }
 
-pub(crate) fn filter(node: &Node) -> FilterResult {
-    let ns_role = ns_role(node);
+fn filter_common(node_state: &NodeState) -> FilterResult {
+    let ns_role = ns_role(node_state);
     if ns_role == unsafe { NSAccessibilityUnknownRole } {
         return FilterResult::ExcludeNode;
     }
 
-    if node.is_hidden() && !node.is_focused() {
+    if node_state.is_hidden() {
         return FilterResult::ExcludeSubtree;
     }
 
     FilterResult::Include
 }
 
+pub(crate) fn filter(node: &Node) -> FilterResult {
+    if node.is_focused() {
+        return FilterResult::Include;
+    }
+
+    filter_common(node.state())
+}
+
+pub(crate) fn filter_detached(node: &DetachedNode) -> FilterResult {
+    if node.is_focused() {
+        return FilterResult::Include;
+    }
+
+    filter_common(node.state())
+}
+
 pub(crate) fn can_be_focused(node: &Node) -> bool {
     filter(node) == FilterResult::Include && node.role() != Role::Window
 }
@@ -396,7 +412,7 @@ declare_class!(
         #[sel(accessibilityRole)]
         fn role(&self) -> *mut NSString {
             let role = self
-                .resolve(ns_role)
+                .resolve(|node| ns_role(node.state()))
                 .unwrap_or(unsafe { NSAccessibilityUnknownRole });
             Id::autorelease_return(role.copy())
         }