Support requesting user attention on macOS (#664)

* Support requesting user attention on macOS

* Documentation improvements

CHANGELOG.md

@@ -26,6 +26,7 @@
 - On X11, drag-and-drop receiving an unsupported drop type can no longer cause the WM to freeze.
 - Fix issue whereby the OpenGL context would not appear at startup on macOS Mojave (#1069).
 - **Breaking:** Removed `From<NSApplicationActivationPolicy>` impl from `ActivationPolicy` on macOS.
+- On macOS, the application can request the user's attention with `WindowExt::request_user_attention`.
 
 # Version 0.17.2 (2018-08-19)
 

src/os/macos.rs

@@ -14,6 +14,14 @@ pub trait WindowExt {
     ///
     /// The pointer will become invalid when the `Window` is destroyed.
     fn get_nsview(&self) -> *mut c_void;
+
+    /// Request user attention, causing the application's dock icon to bounce.
+    /// Note that this has no effect if the application is already focused.
+    ///
+    /// The `is_critical` flag has the following effects:
+    /// - `false`: the dock icon will only bounce once.
+    /// - `true`: the dock icon will bounce until the application is focused.
+    fn request_user_attention(&self, is_critical: bool);
 }
 
 impl WindowExt for Window {
@@ -26,6 +34,11 @@ impl WindowExt for Window {
     fn get_nsview(&self) -> *mut c_void {
         self.window.get_nsview()
     }
+
+    #[inline]
+    fn request_user_attention(&self, is_critical: bool) {
+        self.window.request_user_attention(is_critical)
+    }
 }
 
 /// Corresponds to `NSApplicationActivationPolicy`.

src/platform/macos/window.rs

@@ -9,8 +9,10 @@ use std::sync::atomic::{Ordering, AtomicBool};
 use cocoa::appkit::{
     self,
     CGFloat,
+    NSApp,
     NSApplication,
     NSColor,
+    NSRequestUserAttentionType,
     NSScreen,
     NSView,
     NSWindow,
@@ -585,6 +587,19 @@ impl WindowExt for Window2 {
     fn get_nsview(&self) -> *mut c_void {
         *self.view as *mut c_void
     }
+
+    #[inline]
+    fn request_user_attention(&self, is_critical: bool) {
+        let request_type = if is_critical {
+            NSRequestUserAttentionType::NSCriticalRequest
+        } else {
+            NSRequestUserAttentionType::NSInformationalRequest
+        };
+
+        unsafe {
+            NSApp().requestUserAttention_(request_type);
+        }
+    }
 }
 
 impl Window2 {