fix: AXManualAccessibility showing failure

[codebytere]

Description of Change

Closes #37465.

Fixes an issue where using Swift etc to enable various a11y features within Electron using the AXManualAccessibility attribute would appear to fail. This was happening because we were always calling [super accessibilitySetValue:value forAttribute:attribute] in our override, and the custom attribute would always fail when that superclass function was shown. After this fix, the attribute correctly reflects success, with no failure and the accessibility-support-changed event correctly emitted on app.

I also took the opportunity to update the documentation a little to reflect multiple approaches.

Tested using the Swift REPL and the following code:

import Cocoa
let name = CommandLine.arguments.count >= 2 ? CommandLine.arguments[1] : "Electron"
let pid = NSWorkspace.shared.runningApplications.first(where: {$0.localizedName == name})!.processIdentifier
let axApp = AXUIElementCreateApplication(pid)
let result = AXUIElementSetAttributeValue(axApp, "AXManualAccessibility" as CFString, true as CFTypeRef)
print("Setting 'AXManualAccessibility' \(error.rawValue == 0 ? "succeeded" : "failed")")

Checklist

• PR description included and stakeholders cc'd
• npm test passes
• relevant documentation, tutorials, templates and examples are changed or added
• PR release notes describe the change in a way relevant to app developers, and are capitalized, punctuated, and past tense.

Release Notes

Notes: Fixed an perceived failure when when using Accessibility attribute AXManualAccessibility to enable a11y features in Electron.

[Rhys-T]

Thanks for looking into this.

You know, I didn't even think to check whether it was having the desired effect on the rest of the accessibility tree - I just saw the error and assumed it was actually failing.

Does this also fix reading the attribute's value, or getting the list of attributes to see if it exists?

[MarshallOfSound]

@codebytere this code aligns with upstream. Can we check if they have a similar change and if not try it there first?

[codebytere]

@MarshallOfSound I think you're thinking about the other attribute, AXEnhancedUserInterface - this one is Electron only. We do still align with upstream.

[codebytere]

@Rhys-T

Does this also fix reading the attribute's value, or getting the list of attributes to see if it exists?

can you explain this a little more? What are you specifically trying to do (beyond set the attribute using the above sample code) that is failing?

[release-clerk]

Release Notes Persisted

Fixed an perceived failure when when using Accessibility attribute AXManualAccessibility to enable a11y features in Electron.

[trop]

I was unable to backport this PR to "25-x-y" cleanly;
you will need to perform this backport manually.

[trop]

I was unable to backport this PR to "23-x-y" cleanly;
you will need to perform this backport manually.

[trop]

I was unable to backport this PR to "24-x-y" cleanly;
you will need to perform this backport manually.

[Rhys-T]

@Rhys-T

Does this also fix reading the attribute's value, or getting the list of attributes to see if it exists?

can you explain this a little more? What are you specifically trying to do (beyond set the attribute using the above sample code) that is failing?

I didn't think about this when I was writing the sample code, but: Right now, the array you get by calling AXUIElementCopyAttributeNames on the AXUIElementRef for an Electron app¹ doesn't include AXManualAccessibility. The same is true for the dictionary from AXUIElementCopyAttributeValues². As a result, there's no way for an app using the Accessibility API (e.g. Vimac) to tell that another app actually has support for the AXManualAccessibility attribute³. (It also keeps AXManualAccessibility from showing up in the Accessibility Inspector.)

Also, in AppleScript, you can't even take the "try to set it and ignore the error" approach because of this:

tell application "System Events"
	tell application process "Electron" -- or whatever Electron-based app
		set value of attribute "AXManualAccessibility" to true
		-- System Events got an error: Can’t set attribute "AXManualAccessibility" of application process "Electron" to true.
	end tell
end tell

In System Events, each attribute looks like its own 'object', and since that one "doesn't exist" according to AXUIElementCopyAttributeNames, it throws an error at the attribute "AXManualAccessibility" part and never even attempts to do the set value of part.

Reading the current value of AXManualAccessibility probably isn't as useful, but it seems like it should at least be possible, for consistency with all the other attributes if nothing else.

WebKit, Chromium, and Firefox all seem to implement non-standard AX attributes (e.g. AXDOMIdentifier) by implementing (more of) the same deprecated informal protocol that the current support for AXManualAccessibility is based on:

• accessibilityAttributeNames
• accessibilityAttributeValue:
• accessibilitySetValue:forAttribute: (being implemented by Electron now)
• accessibilityIsAttributeSettable:

I haven't found any equivalent to these in the current, non-deprecated NSAccessibility protocol that Apple wants people to switch to, and it doesn't look to me like the developers of those browsers have found it either.

Footnotes

1. Or the :attributeNames() method in Hammerspoon. ↩

2. Or the :allAttributeValues() method in Hammerspoon. ↩

3. At least if it's being provided by Electron. But as far as I know, nothing else besides Electron implements it yet. ↩

[Rhys-T]

@codebytere Sorry it took so long to get back to you. Not sure if my reply made it to you or not, since the PR was merged/closed by the time I submitted it.

[codebytere]

/trop run backport-to 25-x-y,24-x-y,23-x-y

[trop]

The backport process for this PR has been manually initiated - sending your PR to 25-x-y!

[trop]

The backport process for this PR has been manually initiated - sending your PR to 24-x-y!

[trop]

The backport process for this PR has been manually initiated - sending your PR to 23-x-y!

[trop]

I was unable to backport this PR to "25-x-y" cleanly;
you will need to perform this backport manually.

[trop]

I was unable to backport this PR to "24-x-y" cleanly;
you will need to perform this backport manually.

[trop]

I was unable to backport this PR to "23-x-y" cleanly;
you will need to perform this backport manually.

[trop]

@codebytere has manually backported this PR to "25-x-y", please check out #38146

[trop]

@codebytere has manually backported this PR to "24-x-y", please check out #38147

[trop]

@codebytere has manually backported this PR to "23-x-y", please check out #38151