martin/emacs-doom
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
d6fc21f975d23eedfcef8e968dee5adec5d20cd9
emacs-doom/patches/0006-doc-add-VoiceOver-accessibility-section-to-macOS-app.patch
Daneel d6fc21f975 patches: fix Zoom, j/k line-read, fold/unfold, C-n/C-p (regression fixes) 
Four regressions introduced during review-based refactoring:

1. ZOOM FOCUS JUMPING (P0008 fix in P0000 scope):
   ns_accessibility_enabled guard was added to ns_zoom_track_completion,
   ns_update_end fallback, and ns_draw_window_cursor.  Zoom works
   independently of VoiceOver; ns_accessibility_enabled is only set when
   a screen reader (VoiceOver) activates the AT layer.  Users who use
   Zoom without VoiceOver got no cursor tracking at all.
   Fix: remove ns_accessibility_enabled from all three Zoom call sites;
   guard only with ns_zoom_enabled_p() as in the original.

2. j/k (ANY SINGLE-STEP LINE COMMAND) READS ONLY FIRST WORD:
   The code only treated C-n/C-p (isCtrlNP) as sequential line moves.
   All other line-movement commands (evil j/k, outline-next-heading,
   org-next-visible-heading, etc.) were classified as 'discontiguous'
   jumps, causing VoiceOver to re-anchor and read only a word.
   Fix: detect single-step moves structurally via NSString line-range
   adjacency (NSMaxRange(oldLine) == newLine.location for forward,
   NSMaxRange(newLine) == oldLine.location for backward).  Any command
   that moves exactly one line is sequential --- no command-name
   whitelisting needed, no package-specific code.

3. ORG FOLD/UNFOLD NOT REFRESHING VOICEOVER (P0007):
   BUF_CHARS_MODIFF misses text-property changes such as 'invisible
   used by org-fold-core (org >= 29), outline-mode, hideshow-mode.
   Fix: use BUF_MODIFF; cost is acceptable (rebuild only on VoiceOver
   queries at human interaction speed, not at redisplay speed).

4. C-n/C-p DROPPED LINE-READ (P0005):
   FocusedUIElementChanged posted for ALL emacsMovedCursor moves raced
   with AXSelectedTextChanged(granularity=line) and caused VoiceOver
   to drop the line-read.  Fix: skip FocusedUIElementChanged for
   sequential moves (isCtrlNP or singleLineMove).
2026-03-02 21:10:12 +01:00

136 lines
5.4 KiB
Diff
Raw Blame History

From 4f7f340b5e3e2068b9d20e9fe81f6d0cc20a1340 Mon Sep 17 00:00:00 2001
From: Martin Sukany <martin@sukany.cz>
Date: Sat, 28 Feb 2026 12:58:11 +0100
Subject: [PATCH 6/8] doc: add VoiceOver accessibility section to macOS
appendix
* doc/emacs/macos.texi (VoiceOver Accessibility): New node between
'Mac / GNUstep Events' and 'GNUstep Support'. Document screen reader
usage, keyboard navigation, completion announcements, ns-accessibility-
enabled, and known limitations. Use @xref for cross-reference at
sentence start. Correct description of ns-accessibility-enabled
default: initial value is nil, set automatically at startup.
---
doc/emacs/macos.texi | 76 ++++++++++++++++++++++++++++++++++++++++++++
src/nsterm.m | 10 ++++--
2 files changed, 83 insertions(+), 3 deletions(-)
diff --git a/doc/emacs/macos.texi b/doc/emacs/macos.texi
index 6bd334f48e..8d4a7825d8 100644
--- a/doc/emacs/macos.texi
+++ b/doc/emacs/macos.texi
@@ -36,6 +36,7 @@ Support}), but we hope to improve it in the future.
* Mac / GNUstep Basics:: Basic Emacs usage under GNUstep or macOS.
* Mac / GNUstep Customization:: Customizations under GNUstep or macOS.
* Mac / GNUstep Events:: How window system events are handled.
+* VoiceOver Accessibility:: Screen reader support on macOS.
* GNUstep Support:: Details on status of GNUstep support.
@end menu
@@ -272,6 +273,81 @@ and return the result as a string. You can also use the Lisp function
services and receive the results back. Note that you may need to
restart Emacs to access newly-available services.
+@node VoiceOver Accessibility
+@section VoiceOver Accessibility (macOS)
+@cindex VoiceOver
+@cindex accessibility (macOS)
+@cindex screen reader (macOS)
+@cindex Zoom, cursor tracking (macOS)
+
+ When built with the Cocoa interface on macOS, Emacs exposes buffer
+content, cursor position, mode lines, and interactive elements to the
+macOS accessibility subsystem. This enables use with VoiceOver,
+Apple's built-in screen reader, and with other assistive technology
+such as macOS Zoom.
+
+ Toggle VoiceOver with @kbd{Cmd-F5} (or via System Settings,
+Accessibility, VoiceOver). When Emacs is focused, VoiceOver announces
+the buffer name and current line. Standard Emacs navigation produces
+speech feedback:
+
+@itemize @bullet
+@item
+Arrow keys read individual characters (left/right) or full lines
+(up/down).
+@item
+@kbd{M-f} and @kbd{M-b} announce words.
+@item
+@kbd{C-n} and @kbd{C-p} read the destination line.
+@item
+Shift-modified movement announces selected or deselected text.
+@item
+@key{TAB} and @kbd{S-@key{TAB}} navigate interactive elements
+(buttons, links, completion candidates) within a buffer.
+@end itemize
+
+ The @file{*Completions*} buffer announces each completion candidate
+as you navigate, even while keyboard focus remains in the minibuffer.
+
+ macOS Zoom (System Settings, Accessibility, Zoom) tracks the Emacs
+cursor automatically when set to follow keyboard focus. The cursor
+position is communicated via @code{UAZoomChangeFocus} and the
+@code{AXBoundsForRange} accessibility attribute.
+
+@vindex ns-accessibility-enabled
+ To disable the accessibility interface entirely (for instance, to
+eliminate overhead on systems where assistive technology is not in
+use), set @code{ns-accessibility-enabled} to @code{nil}. Emacs
+detects the presence of assistive technology at startup and sets this
+variable automatically; the initial value is @code{nil}.
+
+@subheading Known Limitations
+
+@itemize @bullet
+@item
+Very large buffers (tens of megabytes) may cause slow initial
+accessibility text extraction. Once cached, subsequent queries
+are fast.
+@item
+Mode-line text extraction handles only character glyphs. Mode lines
+using icon fonts (e.g., icon-based mode-lines)
+produce incomplete accessibility text.
+@item
+The accessibility virtual element tree is rebuilt automatically on
+window configuration changes (splits, deletions, new buffers).
+@item
+Right-to-left (bidi) text is exposed correctly as buffer content,
+but @code{accessibilityRangeForPosition} hit-testing assumes
+left-to-right glyph layout.
+@end itemize
+
+ This support is available only on the Cocoa build. GNUstep has a
+different accessibility model and is not yet supported.
+Block-style cursors are handled
+correctly: character navigation announces the character at the cursor
+position, not the character before it.
+
+
@node GNUstep Support
@section GNUstep Support
diff --git a/src/nsterm.m b/src/nsterm.m
index 7c118045bd..a0598a73c2 100644
--- a/src/nsterm.m
+++ b/src/nsterm.m
@@ -14709,9 +14709,13 @@ Nil means use fullscreen the old (< 10.7) way. The old way works better with
DEFVAR_BOOL ("ns-accessibility-enabled", ns_accessibility_enabled,
doc: /* Non-nil enables Zoom cursor tracking and VoiceOver support.
-Emacs sets this automatically at startup when macOS Zoom is active or
-any assistive technology (VoiceOver, Switch Control, etc.) is connected,
-and updates it whenever that state changes. You can override manually:
+Emacs detects at startup whether macOS Zoom is active or an assistive
+technology (VoiceOver, Switch Control, etc.) is connected, and sets
+this variable accordingly. It updates automatically when accessibility
+state changes. The initial value is nil; it becomes non-nil only when
+an AT is detected.
+
+You can override the auto-detection:
(setq ns-accessibility-enabled t) ; always on
(setq ns-accessibility-enabled nil) ; always off
--
2.43.0
Reference in New Issue View Git Blame Copy Permalink