tauri-nspanel

You can define multiple distinct event handlers within a single tauri_panel! block. This allows you to assign specialized logic to different panels (e.g., a MainPanel vs a UtilityPanel). Each handler is instantiated separately and attached to its respective panel.

tauri_panel! {
    panel!(MainPanel { config: { can_become_key_window: true } })
    panel!(UtilityPanel { config: { is_floating_panel: true, can_become_key_window: false } })
    
    panel_event!(MainPanelEventHandler {
        window_did_become_key(notification: &NSNotification) -> ()
    })
    
    panel_event!(UtilityPanelEventHandler {
        window_did_become_key(notification: &NSNotification) -> ()
    })
}

let main_handler = MainPanelEventHandler::new();
let utility_handler = UtilityPanelEventHandler::new();

// Attach them to their respective panels
main_panel.set_event_handler(Some(main_handler.as_ref()));
utility_panel.set_event_handler(Some(utility_handler.as_ref()));

tauri-nspanel is designed to be compatible with Tauri's multi-threaded architecture and macOS's Cocoa framework requirements.

Key Concepts

• Thread Safety: All panel types implement the Send and Sync traits. This means you can safely pass panels between threads, store them in global state, or use them within async contexts.
• Automatic Main Thread Dispatch: While the panel handles are thread-safe, the actual underlying NSPanel operations (like showing or hiding) must occur on the main thread. The library handles this automatically; when you call a panel method from a background thread or an async task, the operation is internally dispatched to the main thread for you.

Usage Implications

You can safely perform the following without manual thread synchronization:

• Pass panels between threads.
• Store panels in static variables or global state.
• Use panels from async contexts and background tasks.
• Call panel methods from any thread.

use tauri_nspanel::ManagerExt;
use std::sync::Arc;
use tokio::task;

#[tauri::command]
async fn background_panel_operation(app: tauri::AppHandle) {
    // Safe to use from async context
    let panel = app.get_webview_panel("my-panel").unwrap();
    
    // Safe to move into async task
    let panel_clone = Arc::clone(&panel);
    task::spawn(async move {
        // Panel operations automatically dispatch to main thread
        panel_clone.show();
    });
}

To implement hover-based activation, you must configure the panel with can_become_key_window: true and set up a tracking_area that supports mouse entry/exit events. The active_always() option is critical to ensure mouse events are captured even when the application is not currently the active window.

tauri_panel! {
    panel!(HoverActivatePanel {
        config: {
            can_become_main_window: false,
            can_become_key_window: true,
            becomes_key_only_if_needed: true,
            is_floating_panel: true
        }
        with: {
            tracking_area: {
                options: TrackingAreaOptions::new()
                    .active_always()           // Track even when app is inactive
                    .mouse_entered_and_exited() // Get hover notifications
                    .mouse_moved()             // Track mouse movement
                    .cursor_update(),          // Track cursor updates
                auto_resize: true              // Resize tracking area with window
            }
        }
    })
    
    panel_event!(MyPanelEventHandler {})
}

To handle mouse interactions (hover, movement, etc.), you must enable mouse tracking in the panel's with configuration using TrackingAreaOptions.

Once enabled, the following callback methods become available on your event handler:

• on_mouse_entered
• on_mouse_exited
• on_mouse_moved
• on_cursor_update

tauri_panel! {
    panel!(MouseTrackingPanel {
        config: { can_become_key_window: true }
        with: {
            tracking_area: {
                options: TrackingAreaOptions::new()
                    .active_always()
                    .mouse_entered_and_exited()
                    .mouse_moved()
                    .cursor_update(),
                auto_resize: true
            }
        }
    })
    
    panel_event!(MouseTrackingPanelEventHandler {
        window_did_become_key(notification: &NSNotification) -> ()
    })
}

let handler = MouseTrackingPanelEventHandler::new();
handler.on_mouse_entered(|event| {
    println!("Mouse entered the panel");
});

handler.on_mouse_moved(|event| {
    let location = unsafe { event.locationInWindow() };
    println!("Mouse at: x={}, y={}", location.x, location.y);
});

panel.set_event_handler(Some(handler.as_ref()));