patches: add README.txt — full VoiceOver architecture documentation
QA PASS 93.2/100. Covers: architecture, threading model, notification strategy, text cache, completion announcements, interactive spans, Zoom integration, design decisions, known limitations, testing checklist.
This commit is contained in:
549
patches/README.txt
Normal file
549
patches/README.txt
Normal file
@@ -0,0 +1,549 @@
|
|||||||
|
EMACS NS VOICEOVER ACCESSIBILITY PATCH
|
||||||
|
========================================
|
||||||
|
patch: 0001-ns-implement-AXBoundsForRange-for-macOS-Zoom-cursor-.patch
|
||||||
|
author: Martin Sukany <martin@sukany.cz>
|
||||||
|
files: src/nsterm.h (+108 lines)
|
||||||
|
src/nsterm.m (+2560 ins, -140 del, +2420 net)
|
||||||
|
|
||||||
|
|
||||||
|
OVERVIEW
|
||||||
|
--------
|
||||||
|
|
||||||
|
This patch adds comprehensive macOS VoiceOver accessibility support
|
||||||
|
to the Emacs NS (Cocoa) port. Before this patch, Emacs exposed only
|
||||||
|
a minimal, largely broken accessibility interface to macOS assistive
|
||||||
|
technology (AT) clients: EmacsView identified itself as a generic
|
||||||
|
NSAccessibilityGroup with no text content, no cursor tracking, and
|
||||||
|
no notifications. VoiceOver users could activate the application
|
||||||
|
but received no meaningful speech feedback when editing text.
|
||||||
|
|
||||||
|
The patch introduces a layered virtual element tree above EmacsView.
|
||||||
|
Each visible Emacs window is represented by an EmacsAccessibilityBuffer
|
||||||
|
element (AXTextArea / AXTextField for minibuffer) with a full text
|
||||||
|
cache, a visible-run mapping table that bridges buffer character
|
||||||
|
positions to UTF-16 accessibility string indices, and an interactive
|
||||||
|
span child array for Tab navigation. A companion
|
||||||
|
EmacsAccessibilityModeLine element (AXStaticText) represents the mode
|
||||||
|
line of each window. These virtual elements are wired into the macOS
|
||||||
|
Accessibility API through EmacsView acting as the AXGroup root.
|
||||||
|
|
||||||
|
Two additional integration points are provided: (1) macOS Zoom is
|
||||||
|
informed of the cursor position after every physical cursor redraw via
|
||||||
|
UAZoomChangeFocus(), using the correct CoreGraphics (top-left-origin)
|
||||||
|
coordinate space; (2) EmacsView implements accessibilityBoundsForRange:
|
||||||
|
and its legacy parameterized-attribute equivalent so that both Zoom
|
||||||
|
and third-party AT tools can locate the insertion point. The patch
|
||||||
|
also covers completion announcements for the *Completions* buffer and
|
||||||
|
Tab-navigable interactive spans for buttons, links, checkboxes,
|
||||||
|
Org-mode links, completion candidates, and keymap overlays.
|
||||||
|
(EmacsAXSpanTypeCheckBox is reserved for future use but not
|
||||||
|
currently scanned.)
|
||||||
|
|
||||||
|
|
||||||
|
ARCHITECTURE
|
||||||
|
------------
|
||||||
|
|
||||||
|
Class hierarchy (Cocoa only):
|
||||||
|
|
||||||
|
NSAccessibilityElement
|
||||||
|
|
|
||||||
|
+-- EmacsAccessibilityElement (base: owns emacsView + lispWindow)
|
||||||
|
|
|
||||||
|
+-- EmacsAccessibilityBuffer (AXTextArea; one per leaf window)
|
||||||
|
| [category InteractiveSpans] (Tab nav children)
|
||||||
|
|
|
||||||
|
+-- EmacsAccessibilityModeLine (AXStaticText; one per non-mini)
|
||||||
|
|
|
||||||
|
+-- EmacsAccessibilityInteractiveSpan (AXButton/Link/etc.)
|
||||||
|
|
||||||
|
EmacsView (NSView subclass, existing)
|
||||||
|
|
|
||||||
|
+-- owns NSMutableArray *accessibilityElements
|
||||||
|
contains EmacsAccessibilityBuffer + EmacsAccessibilityModeLine
|
||||||
|
instances for every visible leaf window and minibuffer.
|
||||||
|
EmacsAccessibilityInteractiveSpan instances are children of
|
||||||
|
their parent EmacsAccessibilityBuffer, NOT of this array.
|
||||||
|
|
||||||
|
EmacsAccessibilityElement (base class)
|
||||||
|
- Stores a weak (unsafe_unretained) pointer to EmacsView and a
|
||||||
|
Lisp_Object lispWindow (GC-safe window reference).
|
||||||
|
- Provides -validWindow which verifies WINDOW_LIVE_P before
|
||||||
|
returning the raw struct window *. All subclasses use this to
|
||||||
|
avoid dangling pointers after delete-window or kill-buffer.
|
||||||
|
- Provides -screenRectFromEmacsX:y:width:height: which converts
|
||||||
|
EmacsView pixel coordinates (flipped AppKit space) to screen
|
||||||
|
coordinates via the NSWindow coordinate chain.
|
||||||
|
|
||||||
|
EmacsAccessibilityBuffer
|
||||||
|
- Implements the full NSAccessibility text protocol: value, selected
|
||||||
|
text range, line/index/range conversions, frame-for-range,
|
||||||
|
range-for-position, and insertion-point-line-number.
|
||||||
|
- Maintains a text cache (cachedText / visibleRuns) keyed on
|
||||||
|
BUF_MODIFF. The cache is the single source of truth for all
|
||||||
|
index-to-charpos and charpos-to-index mappings.
|
||||||
|
- Detects buffer edits (modiff change), cursor movement (point
|
||||||
|
change), and mark changes, and posts the appropriate
|
||||||
|
NSAccessibility notifications after each redisplay cycle.
|
||||||
|
- Stores cached values for the previous cycle (cachedModiff,
|
||||||
|
cachedPoint, cachedMarkActive) to enable change detection.
|
||||||
|
|
||||||
|
EmacsAccessibilityModeLine
|
||||||
|
- Reads mode line text directly from the window's current glyph
|
||||||
|
matrix (CHAR_GLYPH rows with mode_line_p set).
|
||||||
|
- Stateless: no cache; text is read fresh on every AX query.
|
||||||
|
|
||||||
|
EmacsAccessibilityInteractiveSpan
|
||||||
|
- Lightweight child element representing one contiguous interactive
|
||||||
|
region (button, link, completion item, etc.).
|
||||||
|
- Reports isAccessibilityFocused by comparing cachedPoint of the
|
||||||
|
parent EmacsAccessibilityBuffer against its charpos range.
|
||||||
|
- On setAccessibilityFocused: dispatches to the main queue via
|
||||||
|
GCD to move Emacs point, using block_input around SET_PT_BOTH.
|
||||||
|
|
||||||
|
EmacsView (extensions)
|
||||||
|
- accessibilityElements array: rebuilt by -rebuildAccessibilityTree
|
||||||
|
when the window tree changes (split, delete, new buffer).
|
||||||
|
- -postAccessibilityUpdates: called from ns_update_end() after
|
||||||
|
every redisplay cycle; drives the notification dispatch loop.
|
||||||
|
- lastAccessibilityCursorRect: updated by ns_draw_phys_cursor
|
||||||
|
(C function) for Zoom integration.
|
||||||
|
- Implements accessibilityBoundsForRange: /
|
||||||
|
accessibilityFrameForRange: and the legacy
|
||||||
|
accessibilityAttributeValue:forParameter: API.
|
||||||
|
|
||||||
|
|
||||||
|
THREADING MODEL
|
||||||
|
---------------
|
||||||
|
|
||||||
|
Emacs runs all Lisp evaluation and buffer mutation on the main thread
|
||||||
|
(the Cocoa/AppKit main thread). The macOS Accessibility server
|
||||||
|
(axserver / AT daemon) calls AX getters from a private background
|
||||||
|
thread.
|
||||||
|
|
||||||
|
Rules enforced by this patch:
|
||||||
|
|
||||||
|
Main thread only:
|
||||||
|
- ns_update_end -> postAccessibilityUpdates
|
||||||
|
- rebuildAccessibilityTree / invalidateAccessibilityTree
|
||||||
|
- ensureTextCache / ns_ax_buffer_text (Lisp calls:
|
||||||
|
Fget_char_property, Fnext_single_char_property_change,
|
||||||
|
Fbuffer_substring_no_properties)
|
||||||
|
- postAccessibilityNotificationsForFrame: (full notify logic)
|
||||||
|
- setAccessibilitySelectedTextRange: (SET_PT_BOTH, marker moves)
|
||||||
|
- setAccessibilityFocused: on EmacsAccessibilityInteractiveSpan
|
||||||
|
(dispatches to main queue via dispatch_async)
|
||||||
|
- ns_draw_phys_cursor partial update (lastAccessibilityCursorRect,
|
||||||
|
UAZoomChangeFocus)
|
||||||
|
|
||||||
|
Safe from any thread (no Lisp calls, no mutable Emacs state):
|
||||||
|
- accessibilityIndexForCharpos: reads visibleRuns + cachedText
|
||||||
|
- charposForAccessibilityIndex: same
|
||||||
|
- isAccessibilityFocused on EmacsAccessibilityInteractiveSpan
|
||||||
|
(reads cachedPoint, a plain ptrdiff_t)
|
||||||
|
|
||||||
|
Dispatch-gated (marshalled to main thread when called off-thread):
|
||||||
|
- accessibilityValue (EmacsAccessibilityBuffer)
|
||||||
|
- accessibilitySelectedTextRange
|
||||||
|
- accessibilityInsertionPointLineNumber
|
||||||
|
- accessibilityFrameForRange:
|
||||||
|
- accessibilityRangeForPosition:
|
||||||
|
- accessibilityChildrenInNavigationOrder
|
||||||
|
|
||||||
|
The marshalling pattern used throughout:
|
||||||
|
|
||||||
|
if (![NSThread isMainThread]) {
|
||||||
|
__block T result;
|
||||||
|
dispatch_sync(dispatch_get_main_queue(), ^{ result = ...; });
|
||||||
|
return result;
|
||||||
|
}
|
||||||
|
|
||||||
|
Cached data written on main thread and read from any thread:
|
||||||
|
- cachedText (NSString *): written by ensureTextCache on main.
|
||||||
|
- visibleRuns (ns_ax_visible_run *): written by ensureTextCache.
|
||||||
|
- cachedPoint (ptrdiff_t): plain scalar; atomic on 64-bit ARM/x86.
|
||||||
|
No explicit lock is used; the design relies on the fact that index
|
||||||
|
mapping methods make no Lisp calls and read only the above scalars
|
||||||
|
and the immutable NSString object.
|
||||||
|
|
||||||
|
|
||||||
|
NOTIFICATION STRATEGY
|
||||||
|
---------------------
|
||||||
|
|
||||||
|
Notifications are posted from -postAccessibilityNotificationsForFrame:
|
||||||
|
which runs on the main thread after every redisplay cycle. The
|
||||||
|
method detects three mutually exclusive events:
|
||||||
|
|
||||||
|
1. TEXT CHANGED (modiff != cachedModiff)
|
||||||
|
Posts NSAccessibilityValueChangedNotification with AXTextEditType
|
||||||
|
= Typing and, when exactly one character was inserted, provides
|
||||||
|
AXTextChangeValue for echo feedback. cachedPoint is updated here
|
||||||
|
to suppress a spurious selection-move event in the same cycle
|
||||||
|
(WebKit/Chromium convention: edit and selection-move are mutually
|
||||||
|
exclusive per runloop iteration).
|
||||||
|
|
||||||
|
2. CURSOR MOVED OR MARK CHANGED (point != cachedPoint OR mark change)
|
||||||
|
Granularity is computed by comparing oldIdx and newIdx in
|
||||||
|
cachedText:
|
||||||
|
- different line range -> LINE granularity
|
||||||
|
- same line, distance > 1 UTF-16 unit -> WORD granularity
|
||||||
|
- same line, distance == 1 UTF-16 unit -> CHARACTER granularity
|
||||||
|
C-n / C-p / Tab / backtab force LINE granularity
|
||||||
|
(detected by ns_ax_event_is_line_nav_key which inspects
|
||||||
|
last_command_event) regardless.
|
||||||
|
|
||||||
|
For FOCUSED elements the hybrid strategy applies:
|
||||||
|
|
||||||
|
CHARACTER moves:
|
||||||
|
SelectedTextChanged is posted WITHOUT AXTextSelectionGranularity
|
||||||
|
in userInfo. Omitting the key prevents VoiceOver from deriving
|
||||||
|
its own speech (it would read the character BEFORE point,
|
||||||
|
which is wrong for evil block-cursor mode where the cursor
|
||||||
|
sits ON the character). Then AnnouncementRequested is posted
|
||||||
|
separately with the character AT point as the announcement.
|
||||||
|
Newline is skipped (VoiceOver handles end-of-line internally).
|
||||||
|
|
||||||
|
WORD and LINE moves:
|
||||||
|
SelectedTextChanged is posted WITH AXTextSelectionGranularity.
|
||||||
|
VoiceOver reads the word/line correctly from the element text
|
||||||
|
using the granularity hint. For LINE moves an additional
|
||||||
|
AnnouncementRequested is also posted with the line text (or
|
||||||
|
the completion--string at point if in a completion buffer) to
|
||||||
|
handle C-n/C-p -- VoiceOver processes these keystrokes
|
||||||
|
differently from arrow keys internally.
|
||||||
|
|
||||||
|
SELECTION changes (mark becomes active or extends):
|
||||||
|
SelectedTextChanged with LINE or WORD granularity. VoiceOver
|
||||||
|
reads the newly selected or deselected text.
|
||||||
|
|
||||||
|
For NON-FOCUSED elements (e.g. *Completions* while minibuffer has
|
||||||
|
focus): AnnouncementRequested only. See COMPLETION ANNOUNCEMENTS.
|
||||||
|
|
||||||
|
3. NO CHANGE
|
||||||
|
Nothing is posted. Completion cache is cleared for focused buffer.
|
||||||
|
|
||||||
|
|
||||||
|
TEXT CACHE AND VISIBLE RUNS
|
||||||
|
----------------------------
|
||||||
|
|
||||||
|
ns_ax_buffer_text(w, out_start, out_runs, out_nruns) builds the
|
||||||
|
accessibility string for window W. It operates on the current
|
||||||
|
buffer with set_buffer_internal_1, scanning from BUF_BEGV to BUF_ZV.
|
||||||
|
|
||||||
|
Invisible text detection uses TEXT_PROP_MEANS_INVISIBLE(invis) where
|
||||||
|
invis = Fget_char_property(pos, Qinvisible, Qnil). This respects
|
||||||
|
buffer-invisibility-spec, correctly handling org-mode folding,
|
||||||
|
outline mode, and hideshow -- not just `invisible t' text properties.
|
||||||
|
When an invisible region is found, the scanner jumps ahead using
|
||||||
|
Fnext_single_char_property_change to skip the entire region in O(1)
|
||||||
|
iterations rather than character by character.
|
||||||
|
|
||||||
|
Text extraction uses Fbuffer_substring_no_properties (not raw
|
||||||
|
BUF_BYTE_ADDRESS) to handle the buffer gap correctly. Raw byte
|
||||||
|
access across the gap position yields garbage bytes.
|
||||||
|
|
||||||
|
The ns_ax_visible_run structure:
|
||||||
|
|
||||||
|
typedef struct ns_ax_visible_run {
|
||||||
|
ptrdiff_t charpos; /* Buffer charpos of run start. */
|
||||||
|
ptrdiff_t length; /* Emacs characters in this run. */
|
||||||
|
NSUInteger ax_start; /* UTF-16 index in accessibility string. */
|
||||||
|
NSUInteger ax_length; /* UTF-16 units for this run. */
|
||||||
|
} ns_ax_visible_run;
|
||||||
|
|
||||||
|
Multiple runs are produced when invisible text splits the buffer into
|
||||||
|
non-contiguous visible segments. The mapping array is stored in the
|
||||||
|
EmacsAccessibilityBuffer ivar `visibleRuns' (C array, xmalloc'd).
|
||||||
|
|
||||||
|
Index mapping (charpos <-> ax_index) does a linear scan of the run
|
||||||
|
array. Within a run, UTF-16 unit counting uses
|
||||||
|
rangeOfComposedCharacterSequenceAtIndex: to handle surrogate pairs
|
||||||
|
(emoji, rare CJK) correctly -- one Emacs character may occupy 2
|
||||||
|
UTF-16 units.
|
||||||
|
|
||||||
|
Cache invalidation is triggered whenever BUF_MODIFF changes
|
||||||
|
(ensureTextCache compares cachedTextModiff). The cache is also
|
||||||
|
invalidated when the window tree is rebuilt. NS_AX_TEXT_CAP = 100,000
|
||||||
|
UTF-16 units (~200 KB) caps total exposure; buffers larger than
|
||||||
|
~50,000 lines are truncated for accessibility purposes. VoiceOver
|
||||||
|
performance degrades noticeably beyond this threshold.
|
||||||
|
|
||||||
|
|
||||||
|
COMPLETION ANNOUNCEMENTS
|
||||||
|
------------------------
|
||||||
|
|
||||||
|
When point moves in a non-focused buffer (the common case:
|
||||||
|
*Completions* window while the minibuffer retains keyboard focus),
|
||||||
|
VoiceOver does not automatically read the change because it is
|
||||||
|
tracking the focused element. The patch posts AnnouncementRequested
|
||||||
|
with a 4-step fallback chain to find the best text to announce:
|
||||||
|
|
||||||
|
Step 1 -- completion--string property at point.
|
||||||
|
The `completion--string' text property (set by minibuffer.el
|
||||||
|
since Emacs 29) carries the canonical completion candidate string.
|
||||||
|
It can be a plain Lisp string or a list (CANDIDATE ANNOTATION) where both
|
||||||
|
are strings.
|
||||||
|
ns_ax_completion_string_from_prop handles both: plain string ->
|
||||||
|
use directly; cons -> use car (the candidate without annotation).
|
||||||
|
This is the preferred source: precisely the candidate text with
|
||||||
|
no surrounding whitespace.
|
||||||
|
|
||||||
|
Step 2 -- mouse-face span at point.
|
||||||
|
completion-list-mode marks the active candidate with mouse-face.
|
||||||
|
The code walks backward and forward from point to find the span
|
||||||
|
boundaries, then reads the corresponding slice of cachedText.
|
||||||
|
Used when completion--string is absent (older Emacs or non-
|
||||||
|
standard completion modes).
|
||||||
|
|
||||||
|
Step 3 -- completions-highlight overlay at point.
|
||||||
|
Emacs 29+ highlights the selected completion with the
|
||||||
|
`completions-highlight' face applied via an overlay. The overlay
|
||||||
|
text is extracted via ns_ax_completion_text_for_span which itself
|
||||||
|
tries completion--string first, then the `completion' property,
|
||||||
|
then falls back to the ax string slice.
|
||||||
|
|
||||||
|
Step 4 -- nearest completions-highlight overlay.
|
||||||
|
ns_ax_find_completion_overlay_range scans the buffer for the
|
||||||
|
closest completions-highlight overlay to point. Uses fast probes
|
||||||
|
at {point, point+1, point-1} before falling back to a full O(n)
|
||||||
|
scan.
|
||||||
|
|
||||||
|
Final fallback -- current line text.
|
||||||
|
Read the line containing point from cachedText.
|
||||||
|
|
||||||
|
Deduplication: the announcement is posted only when announceText,
|
||||||
|
overlay bounds, or point have changed since the last cycle
|
||||||
|
(cachedCompletionAnnouncement, cachedCompletionOverlayStart/End,
|
||||||
|
cachedCompletionPoint).
|
||||||
|
|
||||||
|
|
||||||
|
INTERACTIVE SPANS
|
||||||
|
-----------------
|
||||||
|
|
||||||
|
ns_ax_scan_interactive_spans(w, parent_buf) scans the visible range
|
||||||
|
of window W looking for text properties that indicate interactive
|
||||||
|
content. Properties are checked in priority order:
|
||||||
|
|
||||||
|
widget -> EmacsAXSpanTypeWidget (AXButton, via default)
|
||||||
|
button -> EmacsAXSpanTypeButton (AXButton, via default)
|
||||||
|
follow-link -> EmacsAXSpanTypeLink (AXLink)
|
||||||
|
org-link -> EmacsAXSpanTypeLink (AXLink)
|
||||||
|
mouse-face -> EmacsAXSpanTypeCompletionItem
|
||||||
|
(AXButton; completion-list-mode only)
|
||||||
|
keymap overlay-> EmacsAXSpanTypeButton (AXButton)
|
||||||
|
|
||||||
|
For completion buffers (major-mode == completion-list-mode), the span
|
||||||
|
boundary for mouse-face regions uses completion--string as the property
|
||||||
|
key when present, rather than mouse-face itself. This prevents two
|
||||||
|
column-adjacent completion candidates from being merged into one span
|
||||||
|
when their mouse-face regions share padding whitespace.
|
||||||
|
|
||||||
|
All property symbols (Qwidget, Qbutton, Qfollow_link, Qorg_link,
|
||||||
|
Qcompletion__string, Qcompletion, Qcompletions_highlight, Qbacktab,
|
||||||
|
Qcompletion_list_mode) are registered with DEFSYM in syms_of_nsterm
|
||||||
|
and referenced directly -- no repeated intern() calls.
|
||||||
|
|
||||||
|
Each span is allocated, configured, added to the spans array, then
|
||||||
|
released (the array retains it). Label priority: completion--string
|
||||||
|
> buffer substring > help-echo.
|
||||||
|
|
||||||
|
Tab navigation: -accessibilityChildrenInNavigationOrder returns the
|
||||||
|
cached span array, rebuilt lazily when interactiveSpansDirty is set.
|
||||||
|
Calls from off-thread are marshalled with dispatch_sync.
|
||||||
|
|
||||||
|
Focus movement: -setAccessibilityFocused: on a span dispatches
|
||||||
|
Fselect_window + SET_PT_BOTH to the main queue via dispatch_async,
|
||||||
|
wrapped in block_input/unblock_input.
|
||||||
|
|
||||||
|
|
||||||
|
ZOOM INTEGRATION
|
||||||
|
----------------
|
||||||
|
|
||||||
|
macOS Zoom (accessibility zoom) tracks a "focus element" to keep the
|
||||||
|
zoomed viewport centered on the relevant screen area. Two mechanisms
|
||||||
|
are provided:
|
||||||
|
|
||||||
|
1. ns_draw_phys_cursor (C function, main thread, called during
|
||||||
|
redisplay). After clipping the cursor rect to the text area,
|
||||||
|
stores the rect in view->lastAccessibilityCursorRect. If
|
||||||
|
UAZoomEnabled(), converts the rect to screen coordinates and calls
|
||||||
|
UAZoomChangeFocus(kUAZoomFocusTypeInsertionPoint).
|
||||||
|
|
||||||
|
Coordinate conversion chain:
|
||||||
|
EmacsView pixels (AppKit, flipped, origin at top-left of view)
|
||||||
|
-[convertRect:toView:nil]-> NSWindow coordinates
|
||||||
|
-[convertRectToScreen:]-> NSScreen coordinates
|
||||||
|
NSRectToCGRect -> CGRect (same values, no transform)
|
||||||
|
CG y-flip: cgRect.origin.y = primaryH - y - height
|
||||||
|
The flip is required because CoreGraphics uses top-left origin
|
||||||
|
(primary screen) while AppKit screen rects use bottom-left.
|
||||||
|
primaryH = [[NSScreen screens] firstObject].frame.size.height.
|
||||||
|
|
||||||
|
2. EmacsView -accessibilityBoundsForRange: /
|
||||||
|
-accessibilityFrameForRange:
|
||||||
|
AT tools (including Zoom) call these with the selectedTextRange
|
||||||
|
to locate the insertion point. The implementation returns the
|
||||||
|
screen rect stored in lastAccessibilityCursorRect, with a minimum
|
||||||
|
size of 1x8 pixels. The legacy parameterized-attribute API
|
||||||
|
(NSAccessibilityBoundsForRangeParameterizedAttribute) is supported
|
||||||
|
via -accessibilityAttributeValue:forParameter: for older AT
|
||||||
|
clients.
|
||||||
|
|
||||||
|
|
||||||
|
KEY DESIGN DECISIONS
|
||||||
|
--------------------
|
||||||
|
|
||||||
|
1. DEFSYM instead of intern for property symbols.
|
||||||
|
DEFSYM registers symbols at startup (syms_of_nsterm) and stores
|
||||||
|
them in C globals (e.g. Qcompletion__string). Using intern() at
|
||||||
|
every AX scan would perform an obarray lookup on each redisplay
|
||||||
|
cycle. DEFSYM symbols are also always reachable by the GC via
|
||||||
|
staticpro, eliminating any risk of premature collection.
|
||||||
|
|
||||||
|
2. AnnouncementRequested for character moves, not SelectedTextChanged.
|
||||||
|
VoiceOver derives the speech character from SelectedTextChanged by
|
||||||
|
looking at the character BEFORE the new cursor position (the char
|
||||||
|
"passed over"). In evil-mode with a block cursor, the cursor sits
|
||||||
|
ON the character, not between characters. AnnouncementRequested
|
||||||
|
with the character AT point produces correct speech in both insert
|
||||||
|
and normal (block-cursor) modes. SelectedTextChanged is still
|
||||||
|
posted without granularity to interrupt ongoing VoiceOver reading
|
||||||
|
and update braille display tracking.
|
||||||
|
|
||||||
|
3. completion--string, not mouse-face, as span boundary.
|
||||||
|
mouse-face regions in completion-list-mode sometimes include
|
||||||
|
leading or trailing whitespace shared between column-adjacent
|
||||||
|
candidates, which could merge two candidates into one span.
|
||||||
|
completion--string changes precisely at candidate boundaries.
|
||||||
|
|
||||||
|
4. Probe order {point, point+1, point-1} for overlay search.
|
||||||
|
After Tab advances to a new completion candidate, point is at the
|
||||||
|
START of the new entry. The previous entry's overlay covers the
|
||||||
|
position before the new start, so point-1 is inside the OLD
|
||||||
|
overlay. Trying point+1 before point-1 finds the new (correct)
|
||||||
|
entry first.
|
||||||
|
|
||||||
|
5. Notifications posted BEFORE rebuilding the tree.
|
||||||
|
postAccessibilityUpdates uses existing elements which carry cached
|
||||||
|
state from the previous cycle. Rebuilding first would create
|
||||||
|
fresh elements with current values, making change detection
|
||||||
|
impossible. Tree rebuild is deferred to cycles where
|
||||||
|
accessibilityTreeValid is false; no notifications are posted in
|
||||||
|
that cycle.
|
||||||
|
|
||||||
|
6. Re-entrance guard (accessibilityUpdating flag).
|
||||||
|
VoiceOver callbacks triggered by notification posting can cause
|
||||||
|
Cocoa to re-enter the run loop, which may trigger redisplay, which
|
||||||
|
calls ns_update_end -> postAccessibilityUpdates. The BOOL flag
|
||||||
|
breaks this recursion.
|
||||||
|
|
||||||
|
7. lispWindow (Lisp_Object) instead of raw struct window *.
|
||||||
|
struct window pointers can become dangling after delete-window.
|
||||||
|
Storing the Lisp_Object and using WINDOW_LIVE_P + XWINDOW at the
|
||||||
|
call site is the standard safe pattern in Emacs C code.
|
||||||
|
|
||||||
|
8. accessibilityVisibleCharacterRange returns full buffer range.
|
||||||
|
VoiceOver treats the visible range boundary as end-of-text. If
|
||||||
|
this returned only the on-screen portion, VoiceOver would announce
|
||||||
|
"end of text" prematurely when the cursor reaches the visible
|
||||||
|
bottom, even though more buffer content exists below.
|
||||||
|
|
||||||
|
|
||||||
|
KNOWN LIMITATIONS
|
||||||
|
-----------------
|
||||||
|
|
||||||
|
- BUF_OVERLAY_MODIFF is not tracked. Overlay changes (e.g. moving
|
||||||
|
the completions-highlight overlay via Tab without changing buffer
|
||||||
|
text) do not bump BUF_MODIFF, so the text cache is not invalidated.
|
||||||
|
The notification logic detects point changes (cachedPoint) which
|
||||||
|
covers the common case, but overlay-only changes with a stationary
|
||||||
|
point would be missed. A future fix would compare overlay_modiff.
|
||||||
|
|
||||||
|
- Interactive span scan is O(n) in the visible buffer range. Every
|
||||||
|
character position is visited to find property boundaries. For
|
||||||
|
large visible buffers this scan runs on every redisplay cycle
|
||||||
|
whenever interactiveSpansDirty is set. An optimization would use
|
||||||
|
next_single_property_change to skip non-interactive regions in bulk.
|
||||||
|
|
||||||
|
- Mode line text is extracted from CHAR_GLYPH rows only. Image
|
||||||
|
glyphs, stretch glyphs, and composed glyphs are silently skipped.
|
||||||
|
Mode lines with icon fonts (e.g. doom-modeline with nerd-font)
|
||||||
|
produce incomplete or garbled accessibility text.
|
||||||
|
|
||||||
|
- Buffers larger than NS_AX_TEXT_CAP (100,000 UTF-16 units) are
|
||||||
|
truncated. The truncation is silent; AT tools navigating past the
|
||||||
|
truncation boundary may behave unexpectedly.
|
||||||
|
|
||||||
|
- No multi-frame coordination. EmacsView.accessibilityElements is
|
||||||
|
per-view; there is no cross-frame notification ordering.
|
||||||
|
|
||||||
|
- GNUstep is explicitly excluded (#ifdef NS_IMPL_COCOA). GNUstep
|
||||||
|
has a different accessibility model and requires separate work.
|
||||||
|
|
||||||
|
- UAZoomChangeFocus always uses kUAZoomFocusTypeInsertionPoint
|
||||||
|
regardless of cursor style (box, bar, hbar). This is cosmetically
|
||||||
|
imprecise but functionally correct.
|
||||||
|
|
||||||
|
|
||||||
|
TESTING CHECKLIST
|
||||||
|
-----------------
|
||||||
|
|
||||||
|
Prerequisites:
|
||||||
|
- macOS with VoiceOver (Cmd-F5 to toggle).
|
||||||
|
- Emacs built from source with this patch applied.
|
||||||
|
- Evil-mode recommended for block-cursor tests.
|
||||||
|
|
||||||
|
Basic text reading:
|
||||||
|
1. Open Emacs. Press Cmd-F5 to start VoiceOver.
|
||||||
|
2. Switch to Emacs (Cmd-Tab). VoiceOver should announce
|
||||||
|
"Emacs, editor" and read the current line.
|
||||||
|
3. Move cursor with arrow keys. VoiceOver should read each
|
||||||
|
character (left/right) or line (up/down) as you move.
|
||||||
|
4. Verify: right/left arrow reads the character AT the cursor
|
||||||
|
position, not the character left behind. (evil block-cursor)
|
||||||
|
|
||||||
|
Word and line navigation:
|
||||||
|
5. Press M-f / M-b (forward/backward word). VoiceOver should
|
||||||
|
announce the word landed on.
|
||||||
|
6. Press C-n / C-p. VoiceOver should read the full new line.
|
||||||
|
7. Hold Shift and press arrow keys to extend selection. VoiceOver
|
||||||
|
should announce the selected text.
|
||||||
|
|
||||||
|
Completion navigation:
|
||||||
|
8. Type M-x to open the minibuffer.
|
||||||
|
9. Type a partial command name. Press Tab to open *Completions*.
|
||||||
|
10. Press Tab / S-Tab to cycle through completions. VoiceOver
|
||||||
|
should announce each candidate name as you move.
|
||||||
|
11. Verify no double-speech (each candidate read exactly once).
|
||||||
|
|
||||||
|
Interactive span Tab navigation:
|
||||||
|
12. Open a buffer with buttons (e.g. M-x describe-key).
|
||||||
|
13. Use VoiceOver Item Chooser (VO-I) or Tab with VoiceOver
|
||||||
|
interaction mode to navigate interactive elements.
|
||||||
|
14. Verify each button/link is reachable and its label is read.
|
||||||
|
15. In an org-mode file with links, verify links appear as
|
||||||
|
separate navigable AXLink elements.
|
||||||
|
|
||||||
|
Mode line:
|
||||||
|
16. Use the VoiceOver cursor to navigate to the mode line below a
|
||||||
|
buffer. VoiceOver should read the mode line text.
|
||||||
|
|
||||||
|
Zoom integration:
|
||||||
|
17. Enable macOS Zoom (System Settings -> Accessibility -> Zoom).
|
||||||
|
18. Set Zoom to "Follow keyboard focus".
|
||||||
|
19. Move cursor in Emacs. Zoom viewport should track the cursor.
|
||||||
|
20. Verify Zoom follows the cursor across split windows.
|
||||||
|
|
||||||
|
Window operations:
|
||||||
|
21. Split window with C-x 2. VoiceOver should announce a layout
|
||||||
|
change. Switch with C-x o; VoiceOver should read the new
|
||||||
|
window content.
|
||||||
|
22. Delete a window with C-x 0. No crash should occur.
|
||||||
|
23. Switch buffers with C-x b. VoiceOver should read new buffer.
|
||||||
|
|
||||||
|
Stress test:
|
||||||
|
24. Open a large file (>5000 lines). Navigate with C-v / M-v.
|
||||||
|
Verify no significant lag in VoiceOver speech response.
|
||||||
|
25. Open an org-mode file with many folded sections. Verify that
|
||||||
|
folded (invisible) text is not announced during navigation.
|
||||||
|
|
||||||
|
-- end of README --
|
||||||
Reference in New Issue
Block a user