Allow for requesting the user's attention to the window (#2905)

* add method for requesting attention to the main window

* use another enum member for user attention type instead of nested `Option`s

(also, document the enum members now that they don't mirror `winit`)

* update the docstring

Co-authored-by: Emil Ernerfeldt <emil.ernerfeldt@gmail.com>

* add an example app for testing window attention requests

* Apply suggestions from code review

Co-authored-by: Emil Ernerfeldt <emil.ernerfeldt@gmail.com>

* remove `chrono` dependency and improve the attention example's readability

---------

Co-authored-by: Emil Ernerfeldt <emil.ernerfeldt@gmail.com>

crates/egui/src/data/output.rs

@@ -185,6 +185,23 @@ impl OpenUrl {
     }
 }
 
+/// Types of attention to request from a user when a native window is not in focus.
+///
+/// See [winit's documentation][user_attention_type] for platform-specific meaning of the attention types.
+///
+/// [user_attention_type]: https://docs.rs/winit/latest/winit/window/enum.UserAttentionType.html
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum UserAttentionType {
+    /// Request an elevated amount of animations and flair for the window and the task bar or dock icon.
+    Critical,
+
+    /// Request a standard amount of attention-grabbing actions.
+    Informational,
+
+    /// Reset the attention request and interrupt related animations and flashes.
+    Reset,
+}
+
 /// A mouse cursor icon.
 ///
 /// egui emits a [`CursorIcon`] in [`PlatformOutput`] each frame as a request to the integration.

crates/egui/src/lib.rs

@@ -357,7 +357,7 @@ pub use {
     context::Context,
     data::{
         input::*,
-        output::{self, CursorIcon, FullOutput, PlatformOutput, WidgetInfo},
+        output::{self, CursorIcon, FullOutput, PlatformOutput, UserAttentionType, WidgetInfo},
     },
     grid::Grid,
     id::{Id, IdMap},