From 94dd068e15314ba990fb7b96a6c8e4ff100b19c1 Mon Sep 17 00:00:00 2001 From: Ivan Mir Date: Sat, 19 Aug 2017 17:18:12 -0300 Subject: [PATCH 1/5] Special attribute for macOS accessibility #7206 In the linked issue we were discussing that Electron apps are inaccessible unless VoiceOver is enabled. While it's a working solution for users with vision impairment, all other users and apps that require accessibility can't interact with Electron-based software because they don't keep VoiceOver running. I suggest adding `AXManualAccessibility` for programmatically enabling it in Electron apps. The reason for a new attribute is that `AXEnhancedUserInterface` is already reserved by VoiceOver. Adding this attribute will allow both Electron developers and 3rd party developers to enable and disable accessibility from their code by calling `accessibilitySetValue:forAttribute:` on the application. It will be also possible to create a small utility app to switch accessibility in Electron-based apps until there's a native UI solution (like the accessibility settings page in Chrome). --- atom/browser/mac/atom_application.mm | 3 +++ 1 file changed, 3 insertions(+) diff --git a/atom/browser/mac/atom_application.mm b/atom/browser/mac/atom_application.mm index 4a0e18401664..52975e30c7a8 100644 --- a/atom/browser/mac/atom_application.mm +++ b/atom/browser/mac/atom_application.mm @@ -72,6 +72,9 @@ bool enableAccessibility = ([self voiceOverEnabled] && [value boolValue]); [self updateAccessibilityEnabled:enableAccessibility]; } + else if ([attribute isEqualToString:@"AXManualAccessibility"]) { + [self updateAccessibilityEnabled:[value boolValue]]; + } return [super accessibilitySetValue:value forAttribute:attribute]; } From 9605e6cb40af5794d71690cd68b38b4ab7fc3cd4 Mon Sep 17 00:00:00 2001 From: Ivan Mir Date: Tue, 22 Aug 2017 13:01:33 -0300 Subject: [PATCH 2/5] Add documentation for macOS accessibility --- docs/tutorial/accessibility.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/docs/tutorial/accessibility.md b/docs/tutorial/accessibility.md index d256ff5567d5..b56ce294a2af 100644 --- a/docs/tutorial/accessibility.md +++ b/docs/tutorial/accessibility.md @@ -31,3 +31,24 @@ In Devtron, there is a new accessibility tab which will allow you to audit a pag Both of these tools are using the [Accessibility Developer Tools](https://github.com/GoogleChrome/accessibility-developer-tools) library built by Google for Chrome. You can learn more about the accessibility audit rules this library uses on that [repository's wiki](https://github.com/GoogleChrome/accessibility-developer-tools/wiki/Audit-Rules). If you know of other great accessibility tools for Electron, add them to the [accessibility documentation](https://electron.atom.io/docs/tutorial/accessibility) with a pull request. + +### Accessibility on Mac + +Electron applications keep accessibility disabled by default and there are two ways to enable it: +1. By turning on VoiceOver in the Accessibility menu in macOS System Preferences +2. By setting the attribute `AXManualAccessibility` programmatically from the host or 3rd party application. + +```objc +CFStringRef kAXManualAccessibility = CFSTR("AXManualAccessibility"); + ++ (void)enableAccessibility:(BOOL)enable inElectronApplication:(NSRunningApplication *)app +{ + AXUIElementRef appRef = AXUIElementCreateApplication(app.processIdentifier); + if (appRef == nil) + return; + + CFBooleanRef value = enable ? kCFBooleanTrue : kCFBooleanFalse; + AXUIElementSetAttributeValue(appRef, kAXManualAccessibility, value); + CFRelease(appRef); +} +``` From 6717f0d2bb554a39d3359370259eb06d204753aa Mon Sep 17 00:00:00 2001 From: Ivan Mir Date: Thu, 24 Aug 2017 11:22:28 -0300 Subject: [PATCH 3/5] Add accessibility setter to the app --- atom/browser/api/atom_api_app.cc | 14 ++++++++++++++ atom/browser/api/atom_api_app.h | 1 + docs/api/app.md | 9 +++++++++ docs/tutorial/accessibility.md | 20 ++++++++++++++------ 4 files changed, 38 insertions(+), 6 deletions(-) diff --git a/atom/browser/api/atom_api_app.cc b/atom/browser/api/atom_api_app.cc index 06d4dd8aaf5b..d84262430201 100644 --- a/atom/browser/api/atom_api_app.cc +++ b/atom/browser/api/atom_api_app.cc @@ -869,6 +869,18 @@ bool App::IsAccessibilitySupportEnabled() { return ax_state->IsAccessibleBrowser(); } +void App::SetAccessibilitySupportEnabled(bool value) { + auto ax_state = content::BrowserAccessibilityState::GetInstance(); + + if (value) { + ax_state->OnScreenReaderDetected(); + } else { + ax_state->DisableAccessibility(); + } + + Browser::Get()->OnAccessibilitySupportChanged(); +} + Browser::LoginItemSettings App::GetLoginItemSettings(mate::Arguments* args) { Browser::LoginItemSettings options; args->GetNext(&options); @@ -1141,6 +1153,8 @@ void App::BuildPrototype( .SetMethod("relaunch", &App::Relaunch) .SetMethod("isAccessibilitySupportEnabled", &App::IsAccessibilitySupportEnabled) + .SetMethod("setAccessibilitySupportEnabled", + &App::SetAccessibilitySupportEnabled) .SetMethod("disableHardwareAcceleration", &App::DisableHardwareAcceleration) .SetMethod("disableDomainBlockingFor3DAPIs", diff --git a/atom/browser/api/atom_api_app.h b/atom/browser/api/atom_api_app.h index 694a3e304730..a02af4f874b5 100644 --- a/atom/browser/api/atom_api_app.h +++ b/atom/browser/api/atom_api_app.h @@ -171,6 +171,7 @@ class App : public AtomBrowserClient::Delegate, void DisableHardwareAcceleration(mate::Arguments* args); void DisableDomainBlockingFor3DAPIs(mate::Arguments* args); bool IsAccessibilitySupportEnabled(); + void SetAccessibilitySupportEnabled(bool value); Browser::LoginItemSettings GetLoginItemSettings(mate::Arguments* args); #if defined(USE_NSS_CERTS) void ImportCertificate(const base::DictionaryValue& options, diff --git a/docs/api/app.md b/docs/api/app.md index 3ac9ca211b6d..b73e6267f869 100644 --- a/docs/api/app.md +++ b/docs/api/app.md @@ -890,6 +890,15 @@ technologies, such as screen readers, has been detected. See https://www.chromium.org/developers/design-documents/accessibility for more details. +### `app.setAccessibilitySupportEnabled(value)` _macOS_ _Windows_ + +* `value` Boolean - A value for switching the accessibility support + +Manually enables Chrome's accessibility support, allowing to expose accessibility switch to users in application settings. https://www.chromium.org/developers/design-documents/accessibility for more +details. + +**Note:** Rendering accessibility tree can significantly affect the performance of your app. It should not be enabled by default. + ### `app.setAboutPanelOptions(options)` _macOS_ * `options` Object diff --git a/docs/tutorial/accessibility.md b/docs/tutorial/accessibility.md index b56ce294a2af..1648de8ac78f 100644 --- a/docs/tutorial/accessibility.md +++ b/docs/tutorial/accessibility.md @@ -8,7 +8,7 @@ Accessibility concerns in Electron applications are similar to those of websites These new features bring those auditing tools to your Electron app. You can choose to add audits to your tests with Spectron or use them within DevTools with Devtron. Read on for a summary of the tools or checkout our [accessibility documentation](https://electron.atom.io/docs/tutorial/accessibility) for more information. -### Spectron +## Spectron In the testing framework Spectron, you can now audit each window and `` tag in your application. For example: @@ -22,7 +22,7 @@ app.client.auditAccessibility().then(function (audit) { You can read more about this feature in [Spectron's documentation](https://github.com/electron/spectron#accessibility-testing). -### Devtron +## Devtron In Devtron, there is a new accessibility tab which will allow you to audit a page in your app, sort and filter the results. @@ -32,11 +32,19 @@ Both of these tools are using the [Accessibility Developer Tools](https://github If you know of other great accessibility tools for Electron, add them to the [accessibility documentation](https://electron.atom.io/docs/tutorial/accessibility) with a pull request. -### Accessibility on Mac +## Enabling Accessibility -Electron applications keep accessibility disabled by default and there are two ways to enable it: -1. By turning on VoiceOver in the Accessibility menu in macOS System Preferences -2. By setting the attribute `AXManualAccessibility` programmatically from the host or 3rd party application. +Electron applications keep accessibility disabled by default for performance reasons but there are multiple ways to enable it. + +### Inside Application + +By using [`app.setAccessibilitySupportEnabled(value)`](https://electron.atom.io/docs/api/app.md#appsetaccessibilitysupportenabledvalue-macos-windows), you can expose accessibility switch to users in the application preferences. + +### Assistive Technology + +Electron application will enable accessibility automatically when it detects assistive technology (Windows) or VoiceOver (macOS). See Chrome's [accessibility documentation](https://www.chromium.org/developers/design-documents/accessibility#TOC-How-Chrome-detects-the-presence-of-Assistive-Technology) for more details. + +On macOS 3rd party assistive technology can switch accessibility inside Electron applications by setting the attribute `AXManualAccessibility` programmatically: ```objc CFStringRef kAXManualAccessibility = CFSTR("AXManualAccessibility"); From 75b2915feef8e742111f05965d2542d661d7932d Mon Sep 17 00:00:00 2001 From: Ivan Mir Date: Sun, 27 Aug 2017 11:53:25 -0300 Subject: [PATCH 4/5] Change the parameter name for consistency --- atom/browser/api/atom_api_app.cc | 4 ++-- atom/browser/api/atom_api_app.h | 2 +- docs/api/app.md | 4 ++-- docs/tutorial/accessibility.md | 2 +- 4 files changed, 6 insertions(+), 6 deletions(-) diff --git a/atom/browser/api/atom_api_app.cc b/atom/browser/api/atom_api_app.cc index d84262430201..d55dda484d1a 100644 --- a/atom/browser/api/atom_api_app.cc +++ b/atom/browser/api/atom_api_app.cc @@ -869,10 +869,10 @@ bool App::IsAccessibilitySupportEnabled() { return ax_state->IsAccessibleBrowser(); } -void App::SetAccessibilitySupportEnabled(bool value) { +void App::SetAccessibilitySupportEnabled(bool enabled) { auto ax_state = content::BrowserAccessibilityState::GetInstance(); - if (value) { + if (enabled) { ax_state->OnScreenReaderDetected(); } else { ax_state->DisableAccessibility(); diff --git a/atom/browser/api/atom_api_app.h b/atom/browser/api/atom_api_app.h index a02af4f874b5..7f457903803a 100644 --- a/atom/browser/api/atom_api_app.h +++ b/atom/browser/api/atom_api_app.h @@ -171,7 +171,7 @@ class App : public AtomBrowserClient::Delegate, void DisableHardwareAcceleration(mate::Arguments* args); void DisableDomainBlockingFor3DAPIs(mate::Arguments* args); bool IsAccessibilitySupportEnabled(); - void SetAccessibilitySupportEnabled(bool value); + void SetAccessibilitySupportEnabled(bool enabled); Browser::LoginItemSettings GetLoginItemSettings(mate::Arguments* args); #if defined(USE_NSS_CERTS) void ImportCertificate(const base::DictionaryValue& options, diff --git a/docs/api/app.md b/docs/api/app.md index b73e6267f869..0dd898c6b973 100644 --- a/docs/api/app.md +++ b/docs/api/app.md @@ -890,9 +890,9 @@ technologies, such as screen readers, has been detected. See https://www.chromium.org/developers/design-documents/accessibility for more details. -### `app.setAccessibilitySupportEnabled(value)` _macOS_ _Windows_ +### `app.setAccessibilitySupportEnabled(enabled)` _macOS_ _Windows_ -* `value` Boolean - A value for switching the accessibility support +* `enabled` Boolean - Enable or disable accessibility tree rendering Manually enables Chrome's accessibility support, allowing to expose accessibility switch to users in application settings. https://www.chromium.org/developers/design-documents/accessibility for more details. diff --git a/docs/tutorial/accessibility.md b/docs/tutorial/accessibility.md index 1648de8ac78f..194fdfd1170a 100644 --- a/docs/tutorial/accessibility.md +++ b/docs/tutorial/accessibility.md @@ -38,7 +38,7 @@ Electron applications keep accessibility disabled by default for performance rea ### Inside Application -By using [`app.setAccessibilitySupportEnabled(value)`](https://electron.atom.io/docs/api/app.md#appsetaccessibilitysupportenabledvalue-macos-windows), you can expose accessibility switch to users in the application preferences. +By using [`app.setAccessibilitySupportEnabled(enabled)`](https://electron.atom.io/docs/api/app.md#appsetaccessibilitysupportenabledenabled-macos-windows), you can expose accessibility switch to users in the application preferences. ### Assistive Technology From 93a8e7523816a2fc9132b4ce18f330f21021973b Mon Sep 17 00:00:00 2001 From: Ivan Mir Date: Mon, 28 Aug 2017 20:33:16 -0300 Subject: [PATCH 5/5] Add clarifications to the documentation --- docs/api/app.md | 4 ++-- docs/tutorial/accessibility.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/api/app.md b/docs/api/app.md index 0dd898c6b973..83aa234aa88a 100644 --- a/docs/api/app.md +++ b/docs/api/app.md @@ -892,10 +892,10 @@ details. ### `app.setAccessibilitySupportEnabled(enabled)` _macOS_ _Windows_ -* `enabled` Boolean - Enable or disable accessibility tree rendering +* `enabled` Boolean - Enable or disable [accessibility tree](https://developers.google.com/web/fundamentals/accessibility/semantics-builtin/the-accessibility-tree) rendering Manually enables Chrome's accessibility support, allowing to expose accessibility switch to users in application settings. https://www.chromium.org/developers/design-documents/accessibility for more -details. +details. Disabled by default. **Note:** Rendering accessibility tree can significantly affect the performance of your app. It should not be enabled by default. diff --git a/docs/tutorial/accessibility.md b/docs/tutorial/accessibility.md index 194fdfd1170a..d2b6099bba54 100644 --- a/docs/tutorial/accessibility.md +++ b/docs/tutorial/accessibility.md @@ -38,13 +38,13 @@ Electron applications keep accessibility disabled by default for performance rea ### Inside Application -By using [`app.setAccessibilitySupportEnabled(enabled)`](https://electron.atom.io/docs/api/app.md#appsetaccessibilitysupportenabledenabled-macos-windows), you can expose accessibility switch to users in the application preferences. +By using [`app.setAccessibilitySupportEnabled(enabled)`](https://electron.atom.io/docs/api/app.md#appsetaccessibilitysupportenabledenabled-macos-windows), you can expose accessibility switch to users in the application preferences. User's system assistive utilities have priority over this setting and will override it. ### Assistive Technology Electron application will enable accessibility automatically when it detects assistive technology (Windows) or VoiceOver (macOS). See Chrome's [accessibility documentation](https://www.chromium.org/developers/design-documents/accessibility#TOC-How-Chrome-detects-the-presence-of-Assistive-Technology) for more details. -On macOS 3rd party assistive technology can switch accessibility inside Electron applications by setting the attribute `AXManualAccessibility` programmatically: +On macOS, thrid-party assistive technology can switch accessibility inside Electron applications by setting the attribute `AXManualAccessibility` programmatically: ```objc CFStringRef kAXManualAccessibility = CFSTR("AXManualAccessibility");