From ae9424d93aec2f06034e6de3efca4e016836ef62 Mon Sep 17 00:00:00 2001 From: Marat Abdullin Date: Wed, 28 Aug 2019 00:35:34 +0200 Subject: [PATCH] feat: add "accessibleTitle" property to a BrowserWindow instance (#19698) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Sometimes it's necessary to convey more information about the window to screen reader users only (simply putting everything to the window title might be unnecessarily noisy). For example, Chromium uses that technique to tell screen reader users that the window is in incognito mode (the incognito window looks differently and doesn't have «incognito» in the title, but for blind users the screen reader will announce that it's incognito). --- docs/api/browser-window.md | 9 +++++++++ shell/browser/api/atom_api_top_level_window.cc | 10 ++++++++++ shell/browser/api/atom_api_top_level_window.h | 2 ++ shell/browser/native_window.cc | 16 ++++++++++++++++ shell/browser/native_window.h | 9 +++++++++ 5 files changed, 46 insertions(+) diff --git a/docs/api/browser-window.md b/docs/api/browser-window.md index 66a3cdd6cc..117469f20f 100644 --- a/docs/api/browser-window.md +++ b/docs/api/browser-window.md @@ -379,6 +379,9 @@ It creates a new `BrowserWindow` with native properties as set by the `options`. * `disableHtmlFullscreenWindowResize` Boolean (optional) - Whether to prevent the window from resizing when entering HTML Fullscreen. Default is `false`. + * `accessibleTitle` String (optional) - An alternative title string provided only + to accessibility tools such as screen readers. This string is not directly + visible to users. When setting minimum or maximum window size with `minWidth`/`maxWidth`/ `minHeight`/`maxHeight`, it only constrains the users. It won't prevent you from @@ -821,6 +824,12 @@ const menu = Menu.buildFromTemplate(template) Menu.setApplicationMenu(menu) ``` +#### `win.accessibleTitle` + +A `String` property that defines an alternative title provided only to +accessibility tools such as screen readers. This string is not directly +visible to users. + ### Instance Methods Objects created with `new BrowserWindow` have the following instance methods: diff --git a/shell/browser/api/atom_api_top_level_window.cc b/shell/browser/api/atom_api_top_level_window.cc index fae1771620..e489062ac1 100644 --- a/shell/browser/api/atom_api_top_level_window.cc +++ b/shell/browser/api/atom_api_top_level_window.cc @@ -575,6 +575,14 @@ std::string TopLevelWindow::GetTitle() { return window_->GetTitle(); } +void TopLevelWindow::SetAccessibleTitle(const std::string& title) { + window_->SetAccessibleTitle(title); +} + +std::string TopLevelWindow::GetAccessibleTitle() { + return window_->GetAccessibleTitle(); +} + void TopLevelWindow::FlashFrame(bool flash) { window_->FlashFrame(flash); } @@ -1124,6 +1132,8 @@ void TopLevelWindow::BuildPrototype(v8::Isolate* isolate, .SetMethod("getPosition", &TopLevelWindow::GetPosition) .SetMethod("setTitle", &TopLevelWindow::SetTitle) .SetMethod("getTitle", &TopLevelWindow::GetTitle) + .SetProperty("accessibleTitle", &TopLevelWindow::GetAccessibleTitle, + &TopLevelWindow::SetAccessibleTitle) .SetMethod("flashFrame", &TopLevelWindow::FlashFrame) .SetMethod("setSkipTaskbar", &TopLevelWindow::SetSkipTaskbar) .SetMethod("setSimpleFullScreen", &TopLevelWindow::SetSimpleFullScreen) diff --git a/shell/browser/api/atom_api_top_level_window.h b/shell/browser/api/atom_api_top_level_window.h index 418baa4060..cc133c19cb 100644 --- a/shell/browser/api/atom_api_top_level_window.h +++ b/shell/browser/api/atom_api_top_level_window.h @@ -145,6 +145,8 @@ class TopLevelWindow : public mate::TrackableObject, std::vector GetPosition(); void SetTitle(const std::string& title); std::string GetTitle(); + void SetAccessibleTitle(const std::string& title); + std::string GetAccessibleTitle(); void FlashFrame(bool flash); void SetSkipTaskbar(bool skip); void SetExcludedFromShownWindowsMenu(bool excluded); diff --git a/shell/browser/native_window.cc b/shell/browser/native_window.cc index 5208b07d46..60a30a5141 100644 --- a/shell/browser/native_window.cc +++ b/shell/browser/native_window.cc @@ -582,6 +582,22 @@ const views::Widget* NativeWindow::GetWidget() const { return widget(); } +base::string16 NativeWindow::GetAccessibleWindowTitle() const { + if (accessible_title_.empty()) { + return views::WidgetDelegate::GetAccessibleWindowTitle(); + } + + return accessible_title_; +} + +void NativeWindow::SetAccessibleTitle(const std::string& title) { + accessible_title_ = base::UTF8ToUTF16(title); +} + +std::string NativeWindow::GetAccessibleTitle() { + return base::UTF16ToUTF8(accessible_title_); +} + // static void NativeWindowRelay::CreateForWebContents( content::WebContents* web_contents, diff --git a/shell/browser/native_window.h b/shell/browser/native_window.h index b49c7aa26b..d483c9c5ef 100644 --- a/shell/browser/native_window.h +++ b/shell/browser/native_window.h @@ -134,6 +134,11 @@ class NativeWindow : public base::SupportsUserData, virtual void Invalidate() = 0; virtual void SetTitle(const std::string& title) = 0; virtual std::string GetTitle() = 0; + + // Ability to augment the window title for the screen readers. + void SetAccessibleTitle(const std::string& title); + std::string GetAccessibleTitle(); + virtual void FlashFrame(bool flash) = 0; virtual void SetSkipTaskbar(bool skip) = 0; virtual void SetExcludedFromShownWindowsMenu(bool excluded) = 0; @@ -301,6 +306,7 @@ class NativeWindow : public base::SupportsUserData, // views::WidgetDelegate: views::Widget* GetWidget() override; const views::Widget* GetWidget() const override; + base::string16 GetAccessibleWindowTitle() const override; void set_content_view(views::View* view) { content_view_ = view; } @@ -355,6 +361,9 @@ class NativeWindow : public base::SupportsUserData, // Observers of this window. base::ObserverList observers_; + // Accessible title. + base::string16 accessible_title_; + base::WeakPtrFactory weak_factory_; DISALLOW_COPY_AND_ASSIGN(NativeWindow);