Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve accessibility of OakChooser #1216

wants to merge 3 commits into from


Copy link

@dusek dusek commented Mar 9, 2014

These commits improve VoiceOver user experience in the OakChooser. Detailed
description is in each commit's message, but here is a brief summary:

The user can now stay in the search field while using arrow down/up to browse
the search results - VoiceOver will now read the search results in such a case.

To make this more usable, I had to workaround a (supposedly) bug in the way
VoiceOver handles text field accessibility (because it seems there is no
proper NSAccessibility API that VoiceOver can use to implement a reliable

Lastly, since the first commit uses APIs declared only in the 10.9 SDK, I raise
the SDK in the configure script. This is only a proposal as the code without
this SDK change is properly ifdef'ed to handle non-10.9 SDK.

Future work may include announcing current selected item during typing,
possibly with the number of found items.

Quick VoiceOver user summary: after showing the File or Symbol Chooser,
type the search text into the search field (which is automatically focused)
and then move through the results using arrow up and down. If you want to hear
the first result (which is not automatically spoken), first press arrow up
to hear it, then you can use arrows down/up as usual. If you want to browse
the results without entering a search string, quickly type any letter and
delete it to suppress VoiceOver information about menu command and
current window. The space before/after the search text is intentional
and needed as a workaround. Requires OS X Mavericks.

I release these patches to public domain.

This solves accessibility of situation of a user browsing results in
OakChooser (currently File Chooser and Symbol Chooser). Typically
the user is in search field and after typing the search string
wants to use arrow down and up to browse results.

The problem this presented to accessibility was that VoiceOver reads
only changes of selection in the current VoiceOver item. As the user
is on the search field but the selection changes in the results table
below, VoiceOver did not read the various search results when pressing
arrow up/down.

Alternative was to leave the search field, move to the results table,
interact with it and then navigate it with VoiceOver. This is however
not the desired user experience comparable to that of sighted users,
as the VoiceOver user still has to do quite a few steps after entering
the search string to browse the results, not to speak about the situation
when the user would like to change the search string - he/she would need
to leave the table and get back to the search field.

This solves the problem by making the search field (or more generally
any user interface element that triggers change of selection in the
results table, which should be the element the VoiceOver cursor is on)
announce to accessibility the contents of the selected row in search
results table.

See this thread on accessibility-dev mailing list where the options for
implementing such a user interface in an accessible way are discussed:

If the user did not move selection (it is on the first line) and they
want to hear it, they should use arrow up to hear it. Then they can
use arrow down to move through results.
Currently for VoiceOver user when the text cursor is at the end of the search
field (which is 99% of the time) and the user wants to navigate the results
in the table view using arrow down, then after each arrow down, VoiceOver first
plays a "end-of-text" sound, then announces whole contents of the search field,
and only then announces the newly selected search result. (The same happens
when text cursor is at the beginning of the search field and user presses
arrow up.)

This is probably a bug in the way AppKit handles text field accessibility - see

I also reported this as <rdar://problem/16271507>

I hereby present a hacky workaround for this - a subclass of NSSearchField
that tricks accessibility into thinking there is one extra space before and
after the text in the search field. Therefore VoiceOver will not think the user
is at the end of text when they actually are, and therefore will not play the
"end-of-text" sound and announce whole contents of the search field before
getting to the information user wants (the newly selected search result).

While this is a bit hacky, along with the previous commit it allows VoiceOver
to have the same instant great experience as a sighted user when filtering
and browsing results in OakChooser. So I think it's worth the hackiness until
there is a better alternative.

There is only last issue, as currently VoiceOver is very chatty when the
OakChooser window appears: first says "Go to file", if user interrupts it with
an action (i.e. moving VO cursor or typing a character), then VoiceOver starts
telling the whole title of the window, and only after user interrupts it again
does VoiceOver say or announce only the user actions (including search results
table selection change).

So the simpliest if the user wants to start navigating the table items
immediately after showing the OakChooser's window (i.e. without entering
a search term) is to, after showing the OakChooser (e.g. with ⌘T or ⇧⌘T),
quickly type any letter and immediately delete it with backspace and then
use arrow down/up.
Copy link

sorbits commented Mar 10, 2014

Thanks, merged as e7e1aed...129cc27.

Made minor stylistic changes and copied the required accessibility definitions from the 10.9 SDK as it appears they are all available on 10.7 and up, just missing from the earlier SDKs.

The feature also works for the Open Favorites / Recent Projects chooser (⇧⌘O), only the bundle item chooser is unaffected, but this is using old code which should be updated.

@sorbits sorbits closed this Mar 10, 2014
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
None yet
None yet
2 participants