Daneel
67b1d25c34
Split VoiceOver accessibility into 4 logical patches: 0001: Base classes + text extraction (+753) 0002: Buffer/ModeLine/InteractiveSpan implementations (+1716) 0003: EmacsView integration + cursor tracking (+395) 0004: Documentation with known limitations (+75) Each patch is self-contained: 0001 adds infrastructure that compiles but doesn't change behavior. 0002 adds protocol implementations. 0003 wires everything into EmacsView. 0004 documents for users. All patches verified: apply cleanly to current Emacs master, final state identical to original monolithic patch.
505 lines
16 KiB
Diff
505 lines
16 KiB
Diff
From 1bebb38dc851cb4e656fe25078f1e36d54900be5 Mon Sep 17 00:00:00 2001
|
|
From: Martin Sukany <martin@sukany.cz>
|
|
Date: Sat, 28 Feb 2026 09:54:28 +0100
|
|
Subject: [PATCH 3/4] ns: integrate accessibility with EmacsView and redisplay
|
|
|
|
Wire the accessibility infrastructure from the previous patches into
|
|
EmacsView and the redisplay cycle. After this patch, VoiceOver and
|
|
Zoom support is fully active.
|
|
|
|
Integration points:
|
|
|
|
ns_update_end: call [view postAccessibilityUpdates] after each
|
|
redisplay cycle to dispatch queued accessibility notifications.
|
|
|
|
ns_draw_phys_cursor: store cursor rect for Zoom and call
|
|
UAZoomChangeFocus with correct CG coordinate-space transform
|
|
when ns-accessibility-enabled is non-nil.
|
|
|
|
EmacsView dealloc: release accessibilityElements array.
|
|
|
|
windowDidBecomeKey: post FocusedUIElementChangedNotification and
|
|
SelectedTextChanged so VoiceOver tracks the focused buffer on
|
|
app/window switch.
|
|
|
|
EmacsView accessibility methods:
|
|
|
|
rebuildAccessibilityTree: walk Emacs window tree via
|
|
ns_ax_collect_windows to create/reuse virtual elements
|
|
(EmacsAccessibilityBuffer per window, EmacsAccessibilityModeLine
|
|
per mode line).
|
|
|
|
invalidateAccessibilityTree: mark tree dirty; deferred rebuild
|
|
on next AX query.
|
|
|
|
accessibilityChildren, accessibilityFocusedUIElement: expose
|
|
virtual elements to VoiceOver.
|
|
|
|
postAccessibilityUpdates: main notification dispatch. Detects
|
|
three events: window tree change (rebuild + LayoutChanged),
|
|
window switch (focus notification), per-buffer text/cursor
|
|
changes (delegated to buffer elements). Re-entrance guard
|
|
prevents infinite recursion from VoiceOver callbacks.
|
|
|
|
accessibilityBoundsForRange: cursor rect for Zoom, delegates to
|
|
focused buffer element with cursor-rect fallback.
|
|
|
|
Legacy parameterized APIs (accessibilityParameterizedAttribute-
|
|
Names, accessibilityAttributeValue:forParameter:) for pre-10.10
|
|
compatibility.
|
|
|
|
Tested on macOS 14 Sonoma with VoiceOver and Zoom. Full end-to-end:
|
|
buffer navigation, cursor tracking, window switching, completion
|
|
announcements, interactive spans, org-mode folded headings,
|
|
evil-mode block cursor, indirect buffers, multi-window layouts.
|
|
|
|
Known limitations:
|
|
- Bidi text: accessibilityRangeForPosition assumes LTR glyph layout.
|
|
- Mode-line icons: image/stretch glyphs not extracted.
|
|
- Text cap: buffers exceeding NS_AX_TEXT_CAP truncated.
|
|
- Indirect buffers: share modiff_count, may cause redundant cache
|
|
invalidation (correctness preserved, minor performance cost).
|
|
|
|
* src/nsterm.m: EmacsView accessibility integration, cursor tracking.
|
|
---
|
|
src/nsterm.m | 395 +++++++++++++++++++++++++++++++++++++++++++++++++++
|
|
1 file changed, 395 insertions(+)
|
|
|
|
diff --git a/src/nsterm.m b/src/nsterm.m
|
|
index c47912d..34af842 100644
|
|
--- a/src/nsterm.m
|
|
+++ b/src/nsterm.m
|
|
@@ -1105,6 +1105,11 @@ ns_update_end (struct frame *f)
|
|
|
|
unblock_input ();
|
|
ns_updating_frame = NULL;
|
|
+
|
|
+#ifdef NS_IMPL_COCOA
|
|
+ /* Post accessibility notifications after each redisplay cycle. */
|
|
+ [view postAccessibilityUpdates];
|
|
+#endif
|
|
}
|
|
|
|
static void
|
|
@@ -3233,6 +3238,43 @@ ns_draw_window_cursor (struct window *w, struct glyph_row *glyph_row,
|
|
/* Prevent the cursor from being drawn outside the text area. */
|
|
r = NSIntersectionRect (r, ns_row_rect (w, glyph_row, TEXT_AREA));
|
|
|
|
+#ifdef NS_IMPL_COCOA
|
|
+ /* Accessibility: store cursor rect for Zoom and bounds queries.
|
|
+ Skipped when ns-accessibility-enabled is nil to avoid overhead.
|
|
+ VoiceOver notifications are handled solely by
|
|
+ postAccessibilityUpdates (called from ns_update_end)
|
|
+ to avoid duplicate notifications and mid-redisplay fragility. */
|
|
+ {
|
|
+ EmacsView *view = FRAME_NS_VIEW (f);
|
|
+ if (view && on_p && active_p && ns_accessibility_enabled)
|
|
+ {
|
|
+ view->lastAccessibilityCursorRect = r;
|
|
+
|
|
+ /* Tell macOS Zoom where the cursor is. UAZoomChangeFocus()
|
|
+ expects top-left origin (CG coordinate space).
|
|
+ These APIs are available since macOS 10.4 (Universal Access
|
|
+ framework, linked via ApplicationServices umbrella). */
|
|
+#if defined (MAC_OS_X_VERSION_MIN_REQUIRED) \
|
|
+ && MAC_OS_X_VERSION_MIN_REQUIRED >= 101000
|
|
+ if (UAZoomEnabled ())
|
|
+ {
|
|
+ NSRect windowRect = [view convertRect:r toView:nil];
|
|
+ NSRect screenRect = [[view window] convertRectToScreen:windowRect];
|
|
+ CGRect cgRect = NSRectToCGRect (screenRect);
|
|
+
|
|
+ CGFloat primaryH
|
|
+ = [[[NSScreen screens] firstObject] frame].size.height;
|
|
+ cgRect.origin.y
|
|
+ = primaryH - cgRect.origin.y - cgRect.size.height;
|
|
+
|
|
+ UAZoomChangeFocus (&cgRect, &cgRect,
|
|
+ kUAZoomFocusTypeInsertionPoint);
|
|
+ }
|
|
+#endif /* MAC_OS_X_VERSION_MIN_REQUIRED >= 101000 */
|
|
+ }
|
|
+ }
|
|
+#endif
|
|
+
|
|
ns_focus (f, NULL, 0);
|
|
|
|
NSGraphicsContext *ctx = [NSGraphicsContext currentContext];
|
|
@@ -9204,6 +9246,7 @@ ns_ax_completion_text_for_span (EmacsAccessibilityBuffer *elem,
|
|
[layer release];
|
|
#endif
|
|
|
|
+ [accessibilityElements release];
|
|
[[self menu] release];
|
|
[super dealloc];
|
|
}
|
|
@@ -10552,6 +10595,32 @@ ns_in_echo_area (void)
|
|
XSETFRAME (event.frame_or_window, emacsframe);
|
|
kbd_buffer_store_event (&event);
|
|
ns_send_appdefined (-1); // Kick main loop
|
|
+
|
|
+#ifdef NS_IMPL_COCOA
|
|
+ /* Notify VoiceOver that the focused accessibility element changed.
|
|
+ Post on the focused virtual element so VoiceOver starts tracking it.
|
|
+ This is critical for initial focus and app-switch scenarios. */
|
|
+ if (ns_accessibility_enabled)
|
|
+ {
|
|
+ id focused = [self accessibilityFocusedUIElement];
|
|
+ if (focused
|
|
+ && [focused isKindOfClass:[EmacsAccessibilityBuffer class]])
|
|
+ {
|
|
+ ns_ax_post_notification (focused,
|
|
+ NSAccessibilityFocusedUIElementChangedNotification);
|
|
+ NSDictionary *info = @{
|
|
+ @"AXTextStateChangeType":
|
|
+ @(ns_ax_text_state_change_selection_move),
|
|
+ @"AXTextChangeElement": focused
|
|
+ };
|
|
+ ns_ax_post_notification_with_info (focused,
|
|
+ NSAccessibilitySelectedTextChangedNotification, info);
|
|
+ }
|
|
+ else if (focused)
|
|
+ ns_ax_post_notification (focused,
|
|
+ NSAccessibilityFocusedUIElementChangedNotification);
|
|
+ }
|
|
+#endif
|
|
}
|
|
|
|
|
|
@@ -11789,6 +11858,332 @@ ns_in_echo_area (void)
|
|
return fs_state;
|
|
}
|
|
|
|
+#ifdef NS_IMPL_COCOA
|
|
+
|
|
+/* ---- Accessibility: walk the Emacs window tree ---- */
|
|
+
|
|
+static void
|
|
+ns_ax_collect_windows (Lisp_Object window, EmacsView *view,
|
|
+ NSMutableArray *elements,
|
|
+ NSDictionary *existing)
|
|
+{
|
|
+ if (NILP (window))
|
|
+ return;
|
|
+
|
|
+ struct window *w = XWINDOW (window);
|
|
+
|
|
+ if (WINDOW_LEAF_P (w))
|
|
+ {
|
|
+ /* Buffer element — reuse existing if available. */
|
|
+ EmacsAccessibilityBuffer *elem
|
|
+ = [existing objectForKey:[NSValue valueWithPointer:w]];
|
|
+ if (!elem)
|
|
+ {
|
|
+ elem = [[EmacsAccessibilityBuffer alloc] init];
|
|
+ elem.emacsView = view;
|
|
+
|
|
+ /* Initialize cached state to -1 to force first notification. */
|
|
+ elem.cachedModiff = -1;
|
|
+ elem.cachedPoint = -1;
|
|
+ elem.cachedMarkActive = NO;
|
|
+ }
|
|
+ else
|
|
+ {
|
|
+ [elem retain];
|
|
+ }
|
|
+ elem.lispWindow = window;
|
|
+ [elements addObject:elem];
|
|
+ [elem release];
|
|
+
|
|
+ /* Mode line element (skip for minibuffer). */
|
|
+ if (!MINI_WINDOW_P (w))
|
|
+ {
|
|
+ EmacsAccessibilityModeLine *ml
|
|
+ = [[EmacsAccessibilityModeLine alloc] init];
|
|
+ ml.emacsView = view;
|
|
+ ml.lispWindow = window;
|
|
+ [elements addObject:ml];
|
|
+ [ml release];
|
|
+ }
|
|
+ }
|
|
+ else
|
|
+ {
|
|
+ /* Internal (combination) window — recurse into children. */
|
|
+ Lisp_Object child = w->contents;
|
|
+ while (!NILP (child))
|
|
+ {
|
|
+ ns_ax_collect_windows (child, view, elements, existing);
|
|
+ child = XWINDOW (child)->next;
|
|
+ }
|
|
+ }
|
|
+}
|
|
+
|
|
+- (void)rebuildAccessibilityTree
|
|
+{
|
|
+ NSTRACE ("[EmacsView rebuildAccessibilityTree]");
|
|
+ if (!emacsframe)
|
|
+ return;
|
|
+
|
|
+ /* Build map of existing elements by window pointer for reuse. */
|
|
+ NSMutableDictionary *existing = [NSMutableDictionary dictionary];
|
|
+ if (accessibilityElements)
|
|
+ {
|
|
+ for (EmacsAccessibilityElement *elem in accessibilityElements)
|
|
+ {
|
|
+ if ([elem isKindOfClass:[EmacsAccessibilityBuffer class]]
|
|
+ && !NILP (elem.lispWindow))
|
|
+ [existing setObject:elem
|
|
+ forKey:[NSValue valueWithPointer:
|
|
+ XWINDOW (elem.lispWindow)]];
|
|
+ }
|
|
+ }
|
|
+
|
|
+ NSMutableArray *newElements = [NSMutableArray arrayWithCapacity:8];
|
|
+
|
|
+ /* Collect from main window tree. */
|
|
+ Lisp_Object root = FRAME_ROOT_WINDOW (emacsframe);
|
|
+ ns_ax_collect_windows (root, self, newElements, existing);
|
|
+
|
|
+ /* Include minibuffer. */
|
|
+ Lisp_Object mini = emacsframe->minibuffer_window;
|
|
+ if (!NILP (mini))
|
|
+ ns_ax_collect_windows (mini, self, newElements, existing);
|
|
+
|
|
+ [accessibilityElements release];
|
|
+ accessibilityElements = [newElements retain];
|
|
+ accessibilityTreeValid = YES;
|
|
+}
|
|
+
|
|
+- (void)invalidateAccessibilityTree
|
|
+{
|
|
+ accessibilityTreeValid = NO;
|
|
+}
|
|
+
|
|
+- (NSAccessibilityRole)accessibilityRole
|
|
+{
|
|
+ return NSAccessibilityGroupRole;
|
|
+}
|
|
+
|
|
+- (NSString *)accessibilityLabel
|
|
+{
|
|
+ return @"Emacs";
|
|
+}
|
|
+
|
|
+- (BOOL)isAccessibilityElement
|
|
+{
|
|
+ return YES;
|
|
+}
|
|
+
|
|
+- (NSArray *)accessibilityChildren
|
|
+{
|
|
+ if (!accessibilityElements || !accessibilityTreeValid)
|
|
+ [self rebuildAccessibilityTree];
|
|
+ return accessibilityElements;
|
|
+}
|
|
+
|
|
+- (id)accessibilityFocusedUIElement
|
|
+{
|
|
+ if (!emacsframe)
|
|
+ return self;
|
|
+
|
|
+ if (!accessibilityElements || !accessibilityTreeValid)
|
|
+ [self rebuildAccessibilityTree];
|
|
+
|
|
+ for (EmacsAccessibilityElement *elem in accessibilityElements)
|
|
+ {
|
|
+ if ([elem isKindOfClass:[EmacsAccessibilityBuffer class]]
|
|
+ && EQ (elem.lispWindow, emacsframe->selected_window))
|
|
+ return elem;
|
|
+ }
|
|
+ return self;
|
|
+}
|
|
+
|
|
+/* Called from ns_update_end to post AX notifications.
|
|
+
|
|
+ Important: post notifications BEFORE rebuilding the tree.
|
|
+ The existing elements carry cached state (modiff, point) from the
|
|
+ previous redisplay cycle. Rebuilding first would create fresh
|
|
+ elements with current values, making change detection impossible. */
|
|
+- (void)postAccessibilityUpdates
|
|
+{
|
|
+ NSTRACE ("[EmacsView postAccessibilityUpdates]");
|
|
+ eassert ([NSThread isMainThread]);
|
|
+
|
|
+ if (!emacsframe || !ns_accessibility_enabled)
|
|
+ return;
|
|
+
|
|
+ /* Re-entrance guard: VoiceOver callbacks during notification posting
|
|
+ can trigger redisplay, which calls ns_update_end, which calls us
|
|
+ again. Prevent infinite recursion. */
|
|
+ if (accessibilityUpdating)
|
|
+ return;
|
|
+ accessibilityUpdating = YES;
|
|
+
|
|
+ /* Detect window tree change (split, delete, new buffer). Compare
|
|
+ FRAME_ROOT_WINDOW — if it changed, the tree structure changed. */
|
|
+ Lisp_Object curRoot = FRAME_ROOT_WINDOW (emacsframe);
|
|
+ if (!EQ (curRoot, lastRootWindow))
|
|
+ {
|
|
+ lastRootWindow = curRoot;
|
|
+ accessibilityTreeValid = NO;
|
|
+ }
|
|
+
|
|
+ /* If tree is stale, rebuild FIRST so we don't iterate freed
|
|
+ window pointers. Skip notifications for this cycle — the
|
|
+ freshly-built elements have no previous state to diff against. */
|
|
+ if (!accessibilityTreeValid)
|
|
+ {
|
|
+ [self rebuildAccessibilityTree];
|
|
+ /* Invalidate span cache — window layout changed. */
|
|
+ for (EmacsAccessibilityElement *elem in accessibilityElements)
|
|
+ if ([elem isKindOfClass: [EmacsAccessibilityBuffer class]])
|
|
+ [(EmacsAccessibilityBuffer *) elem invalidateInteractiveSpans];
|
|
+ ns_ax_post_notification (self,
|
|
+ NSAccessibilityLayoutChangedNotification);
|
|
+
|
|
+ /* Post focus change so VoiceOver picks up the new tree. */
|
|
+ id focused = [self accessibilityFocusedUIElement];
|
|
+ if (focused && focused != self)
|
|
+ ns_ax_post_notification (focused,
|
|
+ NSAccessibilityFocusedUIElementChangedNotification);
|
|
+
|
|
+ lastSelectedWindow = emacsframe->selected_window;
|
|
+ accessibilityUpdating = NO;
|
|
+ return;
|
|
+ }
|
|
+
|
|
+ /* Post per-buffer notifications using EXISTING elements that have
|
|
+ cached state from the previous cycle. Validate each window
|
|
+ pointer before use. */
|
|
+ for (EmacsAccessibilityElement *elem in accessibilityElements)
|
|
+ {
|
|
+ if ([elem isKindOfClass:[EmacsAccessibilityBuffer class]])
|
|
+ {
|
|
+ struct window *w = [elem validWindow];
|
|
+ if (w && WINDOW_LEAF_P (w)
|
|
+ && BUFFERP (w->contents) && XBUFFER (w->contents))
|
|
+ [(EmacsAccessibilityBuffer *) elem
|
|
+ postAccessibilityNotificationsForFrame:emacsframe];
|
|
+ }
|
|
+ }
|
|
+
|
|
+ /* Check for window switch (C-x o). */
|
|
+ Lisp_Object curSel = emacsframe->selected_window;
|
|
+ BOOL windowSwitched = !EQ (curSel, lastSelectedWindow);
|
|
+ if (windowSwitched)
|
|
+ {
|
|
+ lastSelectedWindow = curSel;
|
|
+ id focused = [self accessibilityFocusedUIElement];
|
|
+ if (focused && focused != self
|
|
+ && [focused isKindOfClass:[EmacsAccessibilityBuffer class]])
|
|
+ {
|
|
+ ns_ax_post_notification (focused,
|
|
+ NSAccessibilityFocusedUIElementChangedNotification);
|
|
+ NSDictionary *info = @{
|
|
+ @"AXTextStateChangeType":
|
|
+ @(ns_ax_text_state_change_selection_move),
|
|
+ @"AXTextChangeElement": focused
|
|
+ };
|
|
+ ns_ax_post_notification_with_info (focused,
|
|
+ NSAccessibilitySelectedTextChangedNotification, info);
|
|
+ }
|
|
+ else if (focused && focused != self)
|
|
+ ns_ax_post_notification (focused,
|
|
+ NSAccessibilityFocusedUIElementChangedNotification);
|
|
+ }
|
|
+
|
|
+ accessibilityUpdating = NO;
|
|
+}
|
|
+
|
|
+/* ---- Cursor position for Zoom (via accessibilityBoundsForRange:) ----
|
|
+
|
|
+ accessibilityFrame returns the VIEW's frame (standard behavior).
|
|
+ The cursor location is exposed through accessibilityBoundsForRange:
|
|
+ which AT tools query using the selectedTextRange. */
|
|
+
|
|
+- (NSRect)accessibilityBoundsForRange:(NSRange)range
|
|
+{
|
|
+ /* Delegate to the focused buffer element for accurate per-range
|
|
+ geometry when possible. Fall back to the cached cursor rect
|
|
+ (set by ns_draw_phys_cursor) for Zoom and simple AT queries. */
|
|
+ id focused = [self accessibilityFocusedUIElement];
|
|
+ if ([focused isKindOfClass:[EmacsAccessibilityBuffer class]])
|
|
+ {
|
|
+ NSRect bufRect = [(EmacsAccessibilityBuffer *) focused
|
|
+ accessibilityFrameForRange:range];
|
|
+ if (!NSIsEmptyRect (bufRect))
|
|
+ return bufRect;
|
|
+ }
|
|
+
|
|
+ NSRect viewRect = lastAccessibilityCursorRect;
|
|
+
|
|
+ if (viewRect.size.width < 1)
|
|
+ viewRect.size.width = 1;
|
|
+ if (viewRect.size.height < 1)
|
|
+ viewRect.size.height = 8;
|
|
+
|
|
+ NSWindow *win = [self window];
|
|
+ if (win == nil)
|
|
+ return NSZeroRect;
|
|
+
|
|
+ NSRect windowRect = [self convertRect:viewRect toView:nil];
|
|
+ return [win convertRectToScreen:windowRect];
|
|
+}
|
|
+
|
|
+/* Modern NSAccessibility protocol entry point. Delegates to
|
|
+ accessibilityBoundsForRange: which holds the real implementation
|
|
+ shared with the legacy parameterized-attribute API. */
|
|
+- (NSRect)accessibilityFrameForRange:(NSRange)range
|
|
+{
|
|
+ return [self accessibilityBoundsForRange:range];
|
|
+}
|
|
+
|
|
+/* Delegate to the focused virtual buffer element so both the modern
|
|
+ and legacy APIs return the correct string data. */
|
|
+- (NSString *)accessibilityStringForRange:(NSRange)range
|
|
+{
|
|
+ id focused = [self accessibilityFocusedUIElement];
|
|
+ if ([focused isKindOfClass:[EmacsAccessibilityBuffer class]])
|
|
+ return [(EmacsAccessibilityBuffer *) focused
|
|
+ accessibilityStringForRange:range];
|
|
+ return @"";
|
|
+}
|
|
+
|
|
+/* ---- Legacy parameterized attribute APIs (Zoom uses these) ---- */
|
|
+
|
|
+- (NSArray *)accessibilityParameterizedAttributeNames
|
|
+{
|
|
+ NSArray *superAttrs = [super accessibilityParameterizedAttributeNames];
|
|
+ if (superAttrs == nil)
|
|
+ superAttrs = @[];
|
|
+ return [superAttrs arrayByAddingObjectsFromArray:
|
|
+ @[NSAccessibilityBoundsForRangeParameterizedAttribute,
|
|
+ NSAccessibilityStringForRangeParameterizedAttribute]];
|
|
+}
|
|
+
|
|
+- (id)accessibilityAttributeValue:(NSString *)attribute
|
|
+ forParameter:(id)parameter
|
|
+{
|
|
+ if ([attribute isEqualToString:
|
|
+ NSAccessibilityBoundsForRangeParameterizedAttribute])
|
|
+ {
|
|
+ NSRange range = [(NSValue *) parameter rangeValue];
|
|
+ return [NSValue valueWithRect:
|
|
+ [self accessibilityBoundsForRange:range]];
|
|
+ }
|
|
+
|
|
+ if ([attribute isEqualToString:
|
|
+ NSAccessibilityStringForRangeParameterizedAttribute])
|
|
+ {
|
|
+ NSRange range = [(NSValue *) parameter rangeValue];
|
|
+ return [self accessibilityStringForRange:range];
|
|
+ }
|
|
+
|
|
+ return [super accessibilityAttributeValue:attribute forParameter:parameter];
|
|
+}
|
|
+
|
|
+#endif /* NS_IMPL_COCOA */
|
|
+
|
|
@end /* EmacsView */
|
|
|
|
|
|
--
|
|
2.43.0
|
|
|