feat: add "accessibleTitle" property to a BrowserWindow instance (#19698

)

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

@@ -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:

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)

shell/browser/api/atom_api_top_level_window.h

@@ -145,6 +145,8 @@ class TopLevelWindow : public mate::TrackableObject<TopLevelWindow>,
   std::vector<int> 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);

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,

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<NativeWindowObserver> observers_;
 
+  // Accessible title.
+  base::string16 accessible_title_;
+
   base::WeakPtrFactory<NativeWindow> weak_factory_;
 
   DISALLOW_COPY_AND_ASSIGN(NativeWindow);