Winit

https://docs.rs/winit/latest/winit
Admin
Winit is a cross-platform Rust library for creating and managing windows and their associated event...
Tokens:658,856
Snippets:6,608
Trust Score:9.7
Update:1 week ago
Show doc for...
Tokens:
Raw
### Example from examples/window.rs (line 59)

Source: https://docs.rs/winit/latest/winit/event_loop/struct.EventLoopProxy.html

An example from the repository showing how to create an EventLoopProxy and use it from a separate thread to send a custom event every second. It includes the main function setup and the thread that sends the event.

```rust
43fn main() -> Result<(), Box<dyn Error>> {
44    #[cfg(web_platform)]
45    console_error_panic_hook::set_once();
46
47    tracing::init();
48
49    let event_loop = EventLoop::<UserEvent>::with_user_event().build()?;
50    let _event_loop_proxy = event_loop.create_proxy();
51
52    // Wire the user event from another thread.
53    #[cfg(not(web_platform))]
54    std::thread::spawn(move || {
55        // Wake up the `event_loop` once every second and dispatch a custom event
56        // from a different thread.
57        info!("Starting to send user event every second");
58        loop {
59            let _ = _event_loop_proxy.send_event(UserEvent::WakeUp);
60            std::thread::sleep(std::time::Duration::from_secs(1));
61        }
62    });
63
64    let mut state = Application::new(&event_loop);
65
66    event_loop.run_app(&mut state).map_err(Into::into)
67}
```

--------------------------------

### Example from examples/pump_events.rs

Source: https://docs.rs/winit/latest/winit/event_loop/struct.ActiveEventLoop.html

Example from the repository showing how to create a window in the resumed callback using create_window.

```rust
fn resumed(&mut self, event_loop: &ActiveEventLoop) {
    let window_attributes = Window::default_attributes().with_title("A fantastic window!");
    self.window = Some(event_loop.create_window(window_attributes).unwrap());
}
```

--------------------------------

### EventLoop::new usage in control_flow example

Source: https://docs.rs/winit/latest/winit/event_loop/struct.EventLoop.html

Example from examples/control_flow.rs showing how to create an EventLoop with EventLoop::new().unwrap() and run an application with run_app. It includes setup for web platform and tracing.

```rust
fn main() -> Result<(), impl std::error::Error> {
    #[cfg(web_platform)]
    console_error_panic_hook::set_once();

    tracing::init();

    info!("Press '1' to switch to Wait mode.");
    info!("Press '2' to switch to WaitUntil mode.");
    info!("Press '3' to switch to Poll mode.");
    info!("Press 'R' to toggle request_redraw() calls.");
    info!("Press 'Esc' to close the window.");

    let event_loop = EventLoop::new().unwrap();

    let mut app = ControlFlowDemo::default();
    event_loop.run_app(&mut app)
}
```

--------------------------------

### Example from examples/control_flow.rs

Source: https://docs.rs/winit/latest/winit/event_loop/struct.ActiveEventLoop.html

Example from the repository showing how to create a window with a title that describes control flow instructions.

```rust
fn resumed(&mut self, event_loop: &ActiveEventLoop) {
    let window_attributes = Window::default_attributes().with_title(
        "Press 1, 2, 3 to change control flow mode. Press R to toggle redraw requests.",
    );
    self.window = Some(event_loop.create_window(window_attributes).unwrap());
}
```

--------------------------------

### swap_dimensions example from examples/window.rs

Source: https://docs.rs/winit/latest/winit/window/struct.Window.html?search=std%3A%3Avec

Shown in the repository example file examples/window.rs around line 697. It reads the current inner size, then swaps width and height to toggle the window dimensions.

```rust
690    fn swap_dimensions(&mut self) {
691        let old_inner_size = self.window.inner_size();
692        let mut inner_size = old_inner_size;
693
694        // ...

```

--------------------------------

### Using LogicalPosition::new in child_window.rs example

Source: https://docs.rs/winit/latest/winit/dpi/struct.LogicalPosition.html

Example from examples/child_window.rs (line 20) showing how to create a LogicalPosition with new(0.0, 0.0) and use it with Position::Logical for window positioning.

```rust
fn main() -> Result<(), impl std::error::Error> {
    use std::collections::HashMap;

    use winit::dpi::{LogicalPosition, LogicalSize, Position};
    use winit::event::{ElementState, Event, KeyEvent, WindowEvent};
    use winit::event_loop::{ActiveEventLoop, EventLoop};
    use winit::raw_window_handle::HasRawWindowHandle;
    use winit::window::Window;

    #[path = "util/fill.rs"]
    mod fill;

    fn spawn_child_window(parent: &Window, event_loop: &ActiveEventLoop) -> Window {
        let parent = parent.raw_window_handle().unwrap();
        let mut window_attributes = Window::default_attributes()
            .with_title("child window")
            .with_inner_size(LogicalSize::new(200.0f32, 200.0f32))
            .with_position(Position::Logical(LogicalPosition::new(0.0, 0.0)))
            .with_visible(true);
        // `with_parent_window` is unsafe. Parent window must be a valid window.
        window_attributes = unsafe { window_attributes.with_parent_window(Some(parent)) };

        event_loop.create_window(window_attributes).unwrap()
    }

    let mut windows = HashMap::new();

    let event_loop: EventLoop<()> = EventLoop::new().unwrap();
    let mut parent_window_id = None;

    event_loop.run(move |event: Event<()>, event_loop| {
        match event {
            Event::Resumed => {
                let attributes = Window::default_attributes()
                    .with_title("parent window")
                    .with_position(Position::Logical(LogicalPosition::new(0.0, 0.0)))
                    .with_inner_size(LogicalSize::new(640.0f32, 480.0f32));
                let window = event_loop.create_window(attributes).unwrap();

                parent_window_id = Some(window.id());

                println!("Parent window id: {parent_window_id:?})");
                windows.insert(window.id(), window);
            },
            Event::WindowEvent { window_id, event } => match event {
                WindowEvent::CloseRequested => {
                    windows.clear();
                    event_loop.exit();
                },
                WindowEvent::CursorEntered { device_id: _ } => {
                    // On x11, println when the cursor entered in a window even if the child window
                    // is created by some key inputs.
                    // the child windows are always placed at (0, 0) with size (200, 200) in the
                    // parent window, so we also can see this log when we move
                    // the cursor around (200, 200) in parent window.
                    println!("cursor entered in the window {window_id:?}");
                },
                WindowEvent::KeyboardInput {
                    event: KeyEvent { state: ElementState::Pressed, .. },
                    ..
                } => {
                    let parent_window = windows.get(&parent_window_id.unwrap()).unwrap();
                    let child_window = spawn_child_window(parent_window, event_loop);
                    let child_id = child_window.id();
                    println!("Child window created with id: {child_id:?}");
                    windows.insert(child_id, child_window);
                },
                WindowEvent::RedrawRequested => {
                    if let Some(window) = windows.get(&window_id) {
                        fill::fill_window(window);
                    }
                },
                _ => (),
            },
            _ => (),
        }
    })
}
```

--------------------------------

### is_visible: Get current window visibility state

Source: https://docs.rs/winit/latest/winit/window/struct.Window.html?search=std%3A%3Avec

Returns the window's current visibility state as an Option<bool>. None means it couldn't be determined.

```rust
let visible = window.is_visible();
```

--------------------------------

### Window management methods from examples/window.rs

Source: https://docs.rs/winit/latest/winit/platform/windows/struct.AnyThread.html?search=std%3A%3Avec

Shows methods for resizing the surface, changing theme, showing window menu, dragging, drag-resizing, and setting occlusion. Includes error handling and logging.

```rust
    fn resize(&mut self, size: PhysicalSize<u32>) {
        info!("Resized to {size:?}");
        #[cfg(not(any(android_platform, ios_platform)))]
        {
            let (width, height) = match (NonZeroU32::new(size.width), NonZeroU32::new(size.height))
            {
                (Some(width), Some(height)) => (width, height),
                _ => return,
            };
            self.surface.resize(width, height).expect("failed to resize inner buffer");
        }
        self.window.request_redraw();
    }

    /// Change the theme that things are drawn in.
    fn set_draw_theme(&mut self, theme: Theme) {
        self.theme = theme;
        self.window.request_redraw();
    }

    /// Show window menu.
    fn show_menu(&self) {
        if let Some(position) = self.cursor_position {
            self.window.show_window_menu(position);
        }
    }

    /// Drag the window.
    fn drag_window(&self) {
        if let Err(err) = self.window.drag_window() {
            info!("Error starting window drag: {err}");
        } else {
            info!("Dragging window Window={:?}", self.window.id());
        }
    }

    /// Drag-resize the window.
    fn drag_resize_window(&self) {
        let position = match self.cursor_position {
            Some(position) => position,
            None => {
                info!("Drag-resize requires cursor to be inside the window");
                return;
            },
        };

        let win_size = self.window.inner_size();
        let border_size = BORDER_SIZE * self.window.scale_factor();

        let x_direction = if position.x < border_size {
            ResizeDirection::West
        } else if position.x > (win_size.width as f64 - border_size) {
            ResizeDirection::East
        } else {
            // Use arbitrary direction instead of None for simplicity.
            ResizeDirection::SouthEast
        };

        let y_direction = if position.y < border_size {
            ResizeDirection::North
        } else if position.y > (win_size.height as f64 - border_size) {
            ResizeDirection::South
        } else {
            // Use arbitrary direction instead of None for simplicity.
            ResizeDirection::SouthEast
        };

        let direction = match (x_direction, y_direction) {
            (ResizeDirection::West, ResizeDirection::North) => ResizeDirection::NorthWest,
            (ResizeDirection::West, ResizeDirection::South) => ResizeDirection::SouthWest,
            (ResizeDirection::West, _) => ResizeDirection::West,
            (ResizeDirection::East, ResizeDirection::North) => ResizeDirection::NorthEast,
            (ResizeDirection::East, ResizeDirection::South) => ResizeDirection::SouthEast,
            (ResizeDirection::East, _) => ResizeDirection::East,
            (_, ResizeDirection::South) => ResizeDirection::South,
            (_, ResizeDirection::North) => ResizeDirection::North,
            _ => return,
        };

        if let Err(err) = self.window.drag_resize_window(direction) {
            info!("Error starting window drag-resize: {err}");
        } else {
            info!("Drag-resizing window Window={:?}", self.window.id());
        }
    }

    /// Change window occlusion state.
    fn set_occluded(&mut self, occluded: bool) {
        self.occluded = occluded;
        if !occluded {
            self.window.request_redraw();
        }
    }
```

--------------------------------

### Example: Get default cursor icon

Source: https://docs.rs/winit/latest/winit/window/enum.CursorIcon.html

Shows how to use the CursorIcon enum to get the default cursor icon.

```rust
use cursor_icon::CursorIcon;

// Get the cursor icon for the default cursor.
let cursor_icon = CursorIcon::Default;
```

--------------------------------

### Create window state using inner_size (examples/window.rs)

Source: https://docs.rs/winit/latest/winit/platform/windows/struct.AnyThread.html?search=

Example from examples/window.rs that creates a window state, retrieving the inner size and setting up cursor, IME, and theme. Includes platform-specific handling for macOS option_as_alt.

```rust
fn new(app: &Application, window: Window) -> Result<Self, Box<dyn Error>> {
    let window = Arc::new(window);

    // SAFETY: the surface is dropped before the `window` which provided it with handle, thus
    // it doesn't outlive it.
    #[cfg(not(any(android_platform, ios_platform)))]
    let surface = Surface::new(app.context.as_ref().unwrap(), Arc::clone(&window))?;

    let theme = window.theme().unwrap_or(Theme::Dark);
    info!("Theme: {theme:?}");
    let named_idx = 0;
    window.set_cursor(CURSORS[named_idx]);

    // Allow IME out of the box.
    let ime = true;
    window.set_ime_allowed(ime);

    let size = window.inner_size();
    let mut state = Self {
        #[cfg(macos_platform)]
        option_as_alt: window.option_as_alt(),
        custom_idx: app.custom_cursors.len() - 1,
        cursor_grab: CursorGrabMode::None,
        named_idx,
```

--------------------------------

### get() example

Source: https://docs.rs/winit/latest/winit/keyboard/struct.SmolStr.html

Returns a subslice of str without panicking. The example shows valid and invalid indices, including out-of-bounds.

```rust
let v = String::from("🗻∈🌏");

assert_eq!(Some("🗻"), v.get(0..4));

// indices not on UTF-8 sequence boundaries
assert!(v.get(1..).is_none());
assert!(v.get(..8).is_none());

// out of bounds
assert!(v.get(..42).is_none());
```

--------------------------------

### Handle window actions with theme and activation token (examples/window.rs)

Source: https://docs.rs/winit/latest/winit/window/struct.Window.html?search=

Example from examples/window.rs (line 240) showing the handle_action method. It removes a window on CloseWindow, requests an activation token on supported platforms when creating a new window, and logs failures.

```rust
196    fn handle_action(&mut self, event_loop: &ActiveEventLoop, window_id: WindowId, action: Action) {
197        // let cursor_position = self.cursor_position;
198        let window = self.windows.get_mut(&window_id).unwrap();
199        info!("Executing action: {action:?}");
200        match action {
201            Action::CloseWindow => {
202                let _ = self.windows.remove(&window_id);
203            },
204            Action::CreateNewWindow => {
205                #[cfg(any(x11_platform, wayland_platform))]
206                if let Err(err) = window.window.request_activation_token() {
207                    info!("Failed to get activation token: {err}");
208                } else {
209                    return;
210                }
211
212                if let Err(err) = window.window.request_activation_token() {
213                    info!(
```

```rust
fn handle_action(&mut self, event_loop: &ActiveEventLoop, window_id: WindowId, action: Action) {
    // let cursor_position = self.cursor_position;
    let window = self.windows.get_mut(&window_id).unwrap();
    info!("Executing action: {action:?}");
    match action {
        Action::CloseWindow => {
            let _ = self.windows.remove(&window_id);
        },
        Action::CreateNewWindow => {
            #[cfg(any(x11_platform, wayland_platform))]
            if let Err(err) = window.window.request_activation_token() {
                info!("Failed to get activation token: {err}");
            } else {
                return;
            }

            if let Err(err) = self.create_window(event_loop) {
                info!(
```

```rust
fn handle_action(&mut self, event_loop: &ActiveEventLoop, window_id: WindowId, action: Action) {
    // let cursor_position = self.cursor_position;
    let window = self.windows.get_mut(&window_id).unwrap();
    info!("Executing action: {action:?}");
    match action {
        Action::CloseWindow => {
            let _ = self.windows.remove(&window_id);
        },
        Action::CreateNewWindow => {
            #[cfg(any(x11_platform, wayland_platform))]
            if let Err(err) = window.window.request_activation_token() {
                info!("Failed to get activation token: {err}");
            } else {
                return;
            }

            if let Err(err) = self.create_window(event_loop) {
                info!(
```

```rust
fn handle_action(&mut self, event_loop: &ActiveEventLoop, window_id: WindowId, action: Action) {
    // let cursor_position = self.cursor_position;
    let window = self.windows.get_mut(&window_id).unwrap();
    info!("Executing action: {action:?}");
    match action {
        Action::CloseWindow => {
            let _ = self.windows.remove(&window_id);
        },
        Action::CreateNewWindow => {
            #[cfg(any(x11_platform, wayland_platform))]
            if let Err(err) = window.window.request_activation_token() {
                info!("Failed to get activation token: {err}");
            } else {
                return;
            }

            if let Err(err) = self.create_window(event_loop) {
                info!(
```

```rust
    fn handle_action(&mut self, event_loop: &ActiveEventLoop, window_id: WindowId, action: Action) {
        // let cursor_position = self.cursor_position;
        let window = self.windows.get_mut(&window_id).unwrap();
        info!("Executing action: {action:?}");
        match action {
            Action::CloseWindow => {
                let _ = self.windows.remove(&window_id);
            },
            Action::CreateNewWindow => {
                #[cfg(any(x11_platform, wayland_platform))]
                if let Err(err) = window.window.request_activation_token() {
                    info!("Failed to get activation token: {err}");
                } else {
                    return;
                }

                if let Err(err) = self.create_window(event_loop) {
                    info!(
```

```rust
fn handle_action(&mut self, event_loop: &ActiveEventLoop, window_id: WindowId, action: Action) {
    // let cursor_position = self.cursor_position;
    let window = self.windows.get_mut(&window_id).unwrap();
    info!("Executing action: {action:?}");
    match action {
        Action::CloseWindow => {
            let _ = self.windows.remove(&window_id);
        },
        Action::CreateNewWindow => {
            #[cfg(any(x11_platform, wayland_platform))]
            if let Err(err) = window.window.request_activation_token() {
                info!(
```

--------------------------------

### NamedKey::to_text example

Source: https://docs.rs/winit/latest/winit/keyboard/enum.NamedKey.html?search=

Shows how to use NamedKey::to_text to get the approximate textual equivalent of a named key. The example asserts that Enter maps to "\r" and F20 maps to None.

```rust
use winit::keyboard::NamedKey;

assert_eq!(NamedKey::Enter.to_text(), Some("\r"));
assert_eq!(NamedKey::F20.to_text(), None);
```

--------------------------------

### Window creation with platform-specific attributes (examples/window.rs)

Source: https://docs.rs/winit/latest/winit/platform/windows/struct.AnyThread.html?search=std%3A%3Avec

Example from examples/window.rs showing window creation with platform-specific attributes and retrieving the window ID.

```rust
125    fn create_window(
126        &mut self,
127        event_loop: &ActiveEventLoop,
128        _tab_id: Option<String>,
129    ) -> Result<WindowId, Box<dyn Error>> {
130        // TODO read-out activation token.
131
132        #[allow(unused_mut)]
133        let mut window_attributes = Window::default_attributes()
134            .with_title("Winit window")
135            .with_transparent(true)
136            .with_window_icon(Some(self.icon.clone()));
137
138        #[cfg(any(x11_platform, wayland_platform))]
139        if let Some(token) = event_loop.read_token_from_env() {
140            startup_notify::reset_activation_token_env();
141            info!("Using token {:?} to activate a window", token);
142            window_attributes = window_attributes.with_activation_token(token);
143        }
144
145        #[cfg(x11_platform)]
146        match std::env::var("X11_VISUAL_ID") {
147            Ok(visual_id_str) => {
148                info!("Using X11 visual id {visual_id_str}");
149                let visual_id = visual_id_str.parse()?;
150                window_attributes = window_attributes.with_x11_visual(visual_id);
151            },
152            Err(_) => info!("Set the X11_VISUAL_ID env variable to request specific X11 visual"),
153        }
154
155        #[cfg(x11_platform)]
156        match std::env::var("X11_SCREEN_ID") {
157            Ok(screen_id_str) => {
158                info!("Placing the window on X11 screen {screen_id_str}");
159                let screen_id = screen_id_str.parse()?;
160                window_attributes = window_attributes.with_x11_screen(screen_id);
161            },
162            Err(_) => info!(
163                "Set the X11_SCREEN_ID env variable to place the window on non-default screen"
164            ),
165        }
166
167        #[cfg(macos_platform)]
168        if let Some(tab_id) = _tab_id {
169            window_attributes = window_attributes.with_tabbing_identifier(&tab_id);
170        }
171
172        #[cfg(web_platform)]
173        {
174            use winit::platform::web::WindowAttributesExtWebSys;
175            window_attributes = window_attributes.with_append(true);
176        }
177
178        let window = event_loop.create_window(window_attributes)?;
179
180        #[cfg(ios_platform)]
181        {
182            use winit::platform::ios::WindowExtIOS;
183            window.recognize_doubletap_gesture(true);
184            window.recognize_pinch_gesture(true);
185            window.recognize_rotation_gesture(true);
186            window.recognize_pan_gesture(true, 2, 2);
187        }
188
189        let window_state = WindowState::new(self, window)?;
190        let window_id = window_state.window.id();
191        info!("Created new window with id={window_id:?}");
192        self.windows.insert(window_id, window_state);
```

--------------------------------

### substr_range example

Source: https://docs.rs/winit/latest/winit/keyboard/struct.SmolStr.html

Shows how to use substr_range to get the range of a substring derived from a string, useful with split.

```rust
use core::range::Range;

let data = "a, b, b, a";
let mut iter = data.split(", ").map(|s| data.substr_range(s).unwrap());

assert_eq!(iter.next(), Some(Range { start: 0, end: 1 }));
assert_eq!(iter.next(), Some(Range { start: 3, end: 4 }));
assert_eq!(iter.next(), Some(Range { start: 6, end: 7 }));
assert_eq!(iter.next(), Some(Range { start: 9, end: 10 }));
```

--------------------------------

### Surface creation with window ID (examples/util/fill.rs)

Source: https://docs.rs/winit/latest/winit/platform/windows/struct.AnyThread.html?search=std%3A%3Avec

Example from examples/util/fill.rs showing how to create a softbuffer surface keyed by window ID.

```rust
54        fn create_surface(
55            &mut self,
56            window: &Window,
57        ) -> &mut Surface<&'static Window, &'static Window> {
58            self.surfaces.entry(window.id()).or_insert_with(|| {
59                Surface::new(&self.context.borrow(), unsafe {
60                    mem::transmute::<&'_ Window, &'static Window>(window)
61                })
62                .expect("Failed to create a softbuffer surface")
63            })
64        }
65
66        fn destroy_surface(&mut self, window: &Window) {
67            self.surfaces.remove(&window.id());
68        }
```

--------------------------------

### Example from examples/window.rs: Window initialization with set_cursor

Source: https://docs.rs/winit/latest/winit/platform/windows/struct.AnyThread.html?search=

Shows a window initialization function that sets a cursor, enables IME, and constructs a state struct. Includes platform-specific cfg attributes for surface creation and option_as_alt. Demonstrates usage of set_cursor, set_ime_allowed, and other window methods.

```rust
554    fn new(app: &Application, window: Window) -> Result<Self, Box<dyn Error>> {
555        let window = Arc::new(window);
556
557        // SAFETY: the surface is dropped before the `window` which provided it with handle, thus
558        // it doesn't outlive it.
559        #[cfg(not(any(android_platform, ios_platform)))]
560        let surface = Surface::new(app.context.as_ref().unwrap(), Arc::clone(&window))?;
561
562        let theme = window.theme().unwrap_or(Theme::Dark);
563        info!("Theme: {theme:?}");
564        let named_idx = 0;
565        window.set_cursor(CURSORS[named_idx]);
566
567        // Allow IME out of the box.
568        let ime = true;
569        window.set_ime_allowed(ime);
570
571        let size = window.inner_size();
572        let mut state = Self {
573            #[cfg(macos_platform)]
574            option_as_alt: window.option_as_alt(),
575            custom_idx: app.custom_cursors.len() - 1,
576            cursor_grab: CursorGrabMode::None,
577            named_idx,
578            #[cfg(not(any(android_platform, ios_platform)))]
579            surface,
580            window,
581            theme,
582            ime,
583            cursor_position: Default::default(),
584            cursor_hidden: Default::default(),
585            modifiers: Default::default(),
586            occluded: Default::default(),
587            rotated: Default::default(),
588            panned: Default::default(),
589            zoom: Default::default(),
590        };
591
592        state.resize(size);
593        Ok(state)
594    }
```

--------------------------------

### trim_start basic usage and directionality

Source: https://docs.rs/winit/latest/winit/keyboard/struct.SmolStr.html

Shows how to use trim_start to remove leading whitespace, with examples for English and Hebrew strings. The directionality example demonstrates that 'start' refers to the first byte position, which is the right side for right-to-left languages.

```rust
let s = "  עברית  ";
assert!(Some('ע') == s.trim_start().chars().next());
```

--------------------------------

### match_indices: collect match indices

Source: https://docs.rs/winit/latest/winit/keyboard/struct.SmolStr.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Example for str::match_indices with a string pattern. Collects tuples of start index and matched substring.

```rust
let v: Vec<_> = "abcXXXabcYYYabc".match_indices("abc").collect();
assert_eq!(v, [(0, "abc"), (6, "abc"), (12, "abc")]);
```

--------------------------------

### Create window with transparency and other attributes (examples/window.rs)

Source: https://docs.rs/winit/latest/winit/window/struct.WindowAttributes.html?search=

This snippet from examples/window.rs shows how to build window attributes with with_transparent(true) and other platform-specific settings. It includes conditional compilation for X11, macOS, web, and iOS platforms.

```rust
fn create_window(
    &mut self,
    event_loop: &ActiveEventLoop,
    _tab_id: Option<String>,
) -> Result<WindowId, Box<dyn Error>> {
    // TODO read-out activation token.

    #[allow(unused_mut)]
    let mut window_attributes = Window::default_attributes()
        .with_title("Winit window")
        .with_transparent(true)
        .with_window_icon(Some(self.icon.clone()));

    #[cfg(any(x11_platform, wayland_platform))]
    if let Some(token) = event_loop.read_token_from_env() {
        startup_notify::reset_activation_token_env();
        info!("Using token {:?} to activate a window", token);
        window_attributes = window_attributes.with_activation_token(token);
    }

    #[cfg(x11_platform)]
    match std::env::var("X11_VISUAL_ID") {
        Ok(visual_id_str) => {
            info!("Using X11 visual id {visual_id_str}");
            let visual_id = visual_id_str.parse()?;
            window_attributes = window_attributes.with_x11_visual(visual_id);
        },
        Err(_) => info!("Set the X11_VISUAL_ID env variable to request specific X11 visual"),
    }

    #[cfg(x11_platform)]
    match std::env::var("X11_SCREEN_ID") {
        Ok(screen_id_str) => {
            info!("Placing the window on X11 screen {screen_id_str}");
            let screen_id = screen_id_str.parse()?;
            window_attributes = window_attributes.with_x11_screen(screen_id);
        },
        Err(_) => info!(
            "Set the X11_SCREEN_ID env variable to place the window on non-default screen"
        ),
    }

    #[cfg(macos_platform)]
    if let Some(tab_id) = _tab_id {
        window_attributes = window_attributes.with_tabbing_identifier(&tab_id);
    }

    #[cfg(web_platform)]
    {
        use winit::platform::web::WindowAttributesExtWebSys;
        window_attributes = window_attributes.with_append(true);
    }

    let window = event_loop.create_window(window_attributes)?;

    #[cfg(ios_platform)]
    {
        use winit::platform::ios::WindowExtIOS;
        window.recognize_doubletap_gesture(true);
        window.recognize_pinch_gesture(true);
        window.recognize_rotation_gesture(true);
        window.recognize_pan_gesture(true, 2, 2);
    }

    let window_state = WindowState::new(self, window)?;
    let window_id = window_state.window.id();
    info!("Created new window with id={window_id:?}");
    self.windows.insert(window_id, window_state);
    Ok(window_id)
}
```

--------------------------------

### trim_start directionality example

Source: https://docs.rs/winit/latest/winit/keyboard/struct.SmolStr.html?search=

Shows that trim_start removes leading whitespace from the start of the byte string, which is the left side for left-to-right languages.

```rust
let s = "  English  ";
assert!(Some('E') == s.trim_start().chars().next());
```

--------------------------------

### rmatch_indices: reverse match indices

Source: https://docs.rs/winit/latest/winit/keyboard/struct.SmolStr.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Example for str::rmatch_indices with a string pattern. Collects tuples of start index and matched substring in reverse order.

```rust
let v: Vec<_> = "abcXXXabcYYYabc".rmatch_indices("abc").collect();
assert_eq!(v, [(12, "abc"), (6, "abc"), (0, "abc")]);
```

--------------------------------

### Example: Handling window events in window.rs

Source: https://docs.rs/winit/latest/winit/keyboard/enum.Key.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Example from `examples/window.rs` showing a `window_event` handler that processes various `WindowEvent` variants, including resizing, focus, scale factor changes, theme changes, redraw requests, and occlusion.

```rust
340    fn window_event(
341        &mut self,
342        event_loop: &ActiveEventLoop,
343        window_id: WindowId,
344        event: WindowEvent,
345    ) {
346        let window = match self.windows.get_mut(&window_id) {
347            Some(window) => window,
348            None => return,
349        };
350
351        match event {
352            WindowEvent::Resized(size) => {
353                window.resize(size);
354            },
355            WindowEvent::Focused(focused) => {
356                if focused {
357                    info!("Window={window_id:?} focused");
358                } else {
359                    info!("Window={window_id:?} unfocused");
360                }
361            },
362            WindowEvent::ScaleFactorChanged { scale_factor, .. } => {
363                info!("Window={window_id:?} changed scale to {scale_factor}");
364            },
365            WindowEvent::ThemeChanged(theme) => {
366                info!("Theme changed to {theme:?}");
367                window.set_draw_theme(theme);
368            },
369            WindowEvent::RedrawRequested => {
370                if let Err(err) = window.draw() {
371                    error!("Error drawing window: {err}");
372                }
373            },
374            WindowEvent::Occluded(occluded) => {
375                // (the rest of the code is not shown in the source)
376            }
377        }
378    }
```

--------------------------------

### EventLoop::builder()

Source: https://docs.rs/winit/latest/winit/event_loop/struct.EventLoop.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Starts building a new event loop. Returns an EventLoopBuilder to allow configuration before creation. Call build on the builder to get the actual event loop.

```APIDOC
## EventLoop::builder()

### Description
Starts building a new event loop. This returns an `EventLoopBuilder`, to allow configuring the event loop before creation. To get the actual event loop, call `build` on that.

### Method
`pub fn builder() -> EventLoopBuilder<()>`

### Parameters
None.

### Returns
- `EventLoopBuilder<()>` - A builder for configuring and creating an event loop.

### Example
```rust
let event_loop = EventLoop::builder().build().unwrap();
```
```

--------------------------------

### Handle window actions including set_theme and theme in examples/window.rs

Source: https://docs.rs/winit/latest/winit/platform/windows/struct.AnyThread.html?search=

This snippet from `examples/window.rs` shows the `handle_action` method that processes various window actions. The `Action::SetTheme(theme)` arm calls `window.window.set_theme(theme)` and then retrieves the actual theme using `window.window.theme()` to update the drawing theme. The snippet is used in the documentation for both `set_theme` and `theme` methods.

```rust
196    fn handle_action(&mut self, event_loop: &ActiveEventLoop, window_id: WindowId, action: Action) {
197        // let cursor_position = self.cursor_position;
198        let window = self.windows.get_mut(&window_id).unwrap();
199        info!("Executing action: {action:?}");
200        match action {
201            Action::CloseWindow => {
202                let _ = self.windows.remove(&window_id);
203            },
204            Action::CreateNewWindow => {
205                #[cfg(any(x11_platform, wayland_platform))]
206                if let Err(err) = window.window.request_activation_token() {
207                    info!("Failed to get activation token: {err}");
208                } else {
209                    return;
210                }
211
212                if let Err(err) = self.create_window(event_loop, None) {
213                    error!("Error creating new window: {err}");
214                }
215            },
216            Action::ToggleResizeIncrements => window.toggle_resize_increments(),
217            Action::ToggleCursorVisibility => window.toggle_cursor_visibility(),
218            Action::ToggleResizable => window.toggle_resizable(),
219            Action::ToggleDecorations => window.toggle_decorations(),
220            Action::ToggleFullscreen => window.toggle_fullscreen(),
221            Action::ToggleMaximize => window.toggle_maximize(),
222            Action::ToggleImeInput => window.toggle_ime(),
223            Action::Minimize => window.minimize(),
224            Action::NextCursor => window.next_cursor(),
225            Action::NextCustomCursor => window.next_custom_cursor(&self.custom_cursors),
226            #[cfg(web_platform)]
227            Action::UrlCustomCursor => window.url_custom_cursor(event_loop),
228            #[cfg(web_platform)]
229            Action::AnimationCustomCursor => {
230                window.animation_custom_cursor(event_loop, &self.custom_cursors)
231            },
232            Action::CycleCursorGrab => window.cycle_cursor_grab(),
233            Action::DragWindow => window.drag_window(),
234            Action::DragResizeWindow => window.drag_resize_window(),
235            Action::ShowWindowMenu => window.show_menu(),
236            Action::PrintHelp => self.print_help(),
237            #[cfg(macos_platform)]
238            Action::CycleOptionAsAlt => window.cycle_option_as_alt(),
239            Action::SetTheme(theme) => {
240                window.window.set_theme(theme);
241                // Get the resulting current theme to draw with
242                let actual_theme = theme.or_else(|| window.window.theme()).unwrap_or(Theme::Dark);
243                window.set_draw_theme(actual_theme);
244            },
245            #[cfg(macos_platform)]
246            Action::CreateNewTab => {
247                let tab_id = window.window.tabbing_identifier();
248                if let Err(err) = self.create_window(event_loop, Some(tab_id)) {
249                    error!("Error creating new window: {err}");
250                }
251            },
252            Action::RequestResize => window.swap_dimensions(),
253        }
254    }
```

--------------------------------

### Key::to_text example

Source: https://docs.rs/winit/latest/winit/keyboard/enum.Key.html

Shows how to use `Key::to_text` to get the textual equivalent of a key. The example asserts that `Key::Character("a")` returns `Some("a")`, `Key::Named(NamedKey::Enter)` returns `Some("\r")`, and `Key::Named(NamedKey::F20)` returns `None`.

```rust
use winit::keyboard::{Key, NamedKey};

assert_eq!(Key::Character("a".into()).to_text(), Some("a"));
assert_eq!(Key::Named(NamedKey::Enter).to_text(), Some("\r"));
assert_eq!(Key::Named(NamedKey::F20).to_text(), None);
```

--------------------------------

### Custom NSApplicationDelegate example

Source: https://docs.rs/winit/latest/winit/platform/macos/index.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Shows how to register a custom NSApplicationDelegate using objc2. Requires macOS 10.11 or higher. Note that to get application:openURLs: to work, you might have to bundle your application. Call sharedApplication after EventLoop::new.

```rust
use objc2::rc::Retained;
use objc2::runtime::ProtocolObject;
use objc2::{declare_class, msg_send_id, mutability, ClassType, DeclaredClass};
use objc2_app_kit::{NSApplication, NSApplicationDelegate};
use objc2_foundation::{NSArray, NSURL, MainThreadMarker, NSObject, NSObjectProtocol};
use winit::event_loop::EventLoop;

declare_class!(
    struct AppDelegate;

    unsafe impl ClassType for AppDelegate {
        type Super = NSObject;
        type Mutability = mutability::MainThreadOnly;
        const NAME: &'static str = "MyAppDelegate";
    }

    impl DeclaredClass for AppDelegate {}

    unsafe impl NSObjectProtocol for AppDelegate {}

    unsafe impl NSApplicationDelegate for AppDelegate {
        #[method(application:openURLs:)]
        fn application_openURLs(&self, application: &NSApplication, urls: &NSArray<NSURL>) {
            // Note: To specifically get `application:openURLs:` to work, you _might_
            // have to bundle your application. This is not done in this example.
            println!("open urls: {application:?}, {urls:?}");
        }
    }
);

impl AppDelegate {
    fn new(mtm: MainThreadMarker) -> Retained<Self> {
        unsafe { msg_send_id![super(mtm.alloc().set_ivars(())), init] }
    }
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let event_loop = EventLoop::new()?;

    let mtm = MainThreadMarker::new().unwrap();
    let delegate = AppDelegate::new(mtm);
    // Important: Call `sharedApplication` after `EventLoop::new`,
    // doing it before is not yet supported.
    let app = NSApplication::sharedApplication(mtm);
    app.setDelegate(Some(ProtocolObject::from_ref(&*delegate)));

    // event_loop.run_app(&mut my_app);
    Ok(())
}
```

--------------------------------

### Window example state with set_cursor and toggles (rust)

Source: https://docs.rs/winit/latest/winit/platform/windows/struct.AnyThread.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Complete implementation of the `new` constructor and toggle helpers for the custom state. Creates a window surface, sets cursor and IME, then initializes the struct. Methods toggle IME, minimization, cursor, maximize, decorations, resizable, cursor visibility, and resize increments.

```rust
fn new(app: &Application, window: Window) -> Result<Self, Box<dyn Error>> {
    let window = Arc::new(window);

    // SAFETY: the surface is dropped before the `window` which provided it with handle, thus
    // it doesn't outlive it.
    #[cfg(not(any(android_platform, ios_platform)))]
    let surface = Surface::new(app.context.as_ref().unwrap(), Arc::clone(&window))?;

    let theme = window.theme().unwrap_or(Theme::Dark);
    info!("Theme: {theme:?}");
    let named_idx = 0;
    window.set_cursor(CURSORS[named_idx]);

    // Allow IME out of the box.
    let ime = true;
    window.set_ime_allowed(ime);

    let size = window.inner_size();
    let mut state = Self {
        #[cfg(macos_platform)]
        option_as_alt: window.option_as_alt(),
        custom_idx: app.custom_cursors.len() - 1,
        cursor_grab: CursorGrabMode::None,
        named_idx,
        #[cfg(not(any(android_platform, ios_platform)))]
        surface,
        window,
        theme,
        ime,
        cursor_position: Default::default(),
        cursor_hidden: Default::default(),
        modifiers: Default::default(),
        occluded: Default::default(),
        rotated: Default::default(),
        panned: Default::default(),
        zoom: Default::default(),
    };

    state.resize(size);
    Ok(state)
}

pub fn toggle_ime(&mut self) {
    self.ime = !self.ime;
    self.window.set_ime_allowed(self.ime);
    if let Some(position) = self.ime.then_some(self.cursor_position).flatten() {
        self.window.set_ime_cursor_area(position, PhysicalSize::new(20, 20));
    }
}

pub fn minimize(&mut self) {
    self.window.set_minimized(true);
}

pub fn cursor_moved(&mut self, position: PhysicalPosition<f64>) {
    self.cursor_position = Some(position);
    if self.ime {
        self.window.set_ime_cursor_area(position, PhysicalSize::new(20, 20));
    }
}

pub fn cursor_left(&mut self) {
    self.cursor_position = None;
}

/// Toggle maximized.
fn toggle_maximize(&self) {
    let maximized = self.window.is_maximized();
    self.window.set_maximized(!maximized);
}

/// Toggle window decorations.
fn toggle_decorations(&self) {
    let decorated = self.window.is_decorated();
    self.window.set_decorations(!decorated);
}

/// Toggle window resizable state.
fn toggle_resizable(&self) {
    let resizable = self.window.is_resizable();
    self.window.set_resizable(!resizable);
}

/// Toggle cursor visibility
fn toggle_cursor_visibility(&mut self) {
    self.cursor_hidden = !self.cursor_hidden;
    self.window.set_cursor_visible(!self.cursor_hidden);
}

/// Toggle resize increments on a window.
fn toggle_resize_increments(&mut self) {
    let new_increments = match self.window.resize_increments() {
        Some(_) => None,
        None => Some(LogicalSize::new(25.0, 25.0)),
    };
    info!("Had increments: {}", new_increments.is_none());
}
```

--------------------------------

### Create window with platform-specific attributes (examples/window.rs)

Source: https://docs.rs/winit/latest/winit/event_loop/struct.ActiveEventLoop.html

Shows how to create a window using ActiveEventLoop::create_window, applying platform-specific attributes such as activation token, X11 visual/screen, macOS tabbing identifier, and web append. Also enables iOS gesture recognition.

```rust
125    fn create_window(
126        &mut self,
127        event_loop: &ActiveEventLoop,
128        _tab_id: Option<String>,
129    ) -> Result<WindowId, Box<dyn Error>> {
130        // TODO read-out activation token.
131
132        #[allow(unused_mut)]
133        let mut window_attributes = Window::default_attributes()
134            .with_title("Winit window")
135            .with_transparent(true)
136            .with_window_icon(Some(self.icon.clone()));
137
138        #[cfg(any(x11_platform, wayland_platform))]
139        if let Some(token) = event_loop.read_token_from_env() {
140            startup_notify::reset_activation_token_env();
141            info!("Using token {:?} to activate a window", token);
142            window_attributes = window_attributes.with_activation_token(token);
143        }
144
145        #[cfg(x11_platform)]
146        match std::env::var("X11_VISUAL_ID") {
147            Ok(visual_id_str) => {
148                info!("Using X11 visual id {visual_id_str}");
149                let visual_id = visual_id_str.parse()?;
150                window_attributes = window_attributes.with_x11_visual(visual_id);
151            },
152            Err(_) => info!("Set the X11_VISUAL_ID env variable to request specific X11 visual"),
153        }
154
155        #[cfg(x11_platform)]
156        match std::env::var("X11_SCREEN_ID") {
157            Ok(screen_id_str) => {
158                info!("Placing the window on X11 screen {screen_id_str}");
159                let screen_id = screen_id_str.parse()?;
160                window_attributes = window_attributes.with_x11_screen(screen_id);
161            },
162            Err(_) => info!(
163                "Set the X11_SCREEN_ID env variable to place the window on non-default screen"
164            ),
165        }
166
167        #[cfg(macos_platform)]
168        if let Some(tab_id) = _tab_id {
169            window_attributes = window_attributes.with_tabbing_identifier(&tab_id);
170        }
171
172        #[cfg(web_platform)]
173        {
174            use winit::platform::web::WindowAttributesExtWebSys;
175            window_attributes = window_attributes.with_append(true);
176        }
177
178        let window = event_loop.create_window(window_attributes)?;
179
180        #[cfg(ios_platform)]
181        {
182            use winit::platform::ios::WindowExtIOS;
183            window.recognize_doubletap_gesture(true);
184            window.recognize_pinch_gesture(true);
185            window.recognize_rotation_gesture(true);
186            window.recognize_pan_gesture(true, 2, 2);
187        }
188
189        let window_state = WindowState::new(self, window)?;
190        let window_id = window_state.window.id();
191        info!("Created new window with id={window_id:?}");
192        self.windows.insert(window_id, window_state);
193        Ok(window_id)
194    }
```

--------------------------------

### char_indices: Unicode combining characters

Source: https://docs.rs/winit/latest/winit/keyboard/struct.SmolStr.html

Shows that `char_indices` yields byte positions, not visual character positions. The example uses "y̆es" where the combining mark takes two bytes, so the next character starts at byte 3.

```rust
let yes = "y̆es";

let mut char_indices = yes.char_indices();

assert_eq!(Some((0, 'y')), char_indices.next()); // not (0, 'y̆')
assert_eq!(Some((1, '\u{0306}')), char_indices.next());

// note the 3 here - the previous character took up two bytes
assert_eq!(Some((3, 'e')), char_indices.next());
assert_eq!(Some((4, 's')), char_indices.next());

assert_eq!(None, char_indices.next());
```
Tokens:
Raw