baseview

PlatformHandle is a lightweight, cheaply cloneable, and thread-safe (Send + Sync) handle to a window and its display connection.

Use PlatformHandle when you need to pass window information to other threads. It implements both HasWindowHandle and HasDisplayHandle from the raw-window-handle crate.

Important Considerations:

• Weak Handle: It is a weak handle. If the window it refers to is destroyed, methods like window_handle() will return HandleError::Unavailable.
• Thread Safety: While it is Send and Sync, platform limitations may apply. On some platforms, calling window_handle() from a thread other than the main thread may return HandleError::Unavailable even if the window is still alive.
• Creation: You can obtain a PlatformHandle from a WindowContext using the platform_handle() method.

// Obtaining a PlatformHandle from WindowContext
let handle = window_context.platform_handle();

// The handle can be sent to another thread
std::thread::spawn(move || {
    if let Ok(window_handle) = handle.window_handle() {
        // Use the window handle
    }
});

In baseview, a Window manages its own lifecycle. Unlike other libraries where you might manage the event loop externally, the Window owns its associated WindowHandler and Host types.

Key Lifecycle Rules:

• Creation: Use Window::create or Window::create_with_host. This creates the window but does not show it. You must call .show() or .run_until_closed() to make it visible.
• Destruction: Dropping the Window handle will always destroy the window and its associated handler/host. You can also call .close() to explicitly destroy it.
• Unexpected Closure: A window can be destroyed before you drop the handle if:
  • The WindowHandler requests a close (e.g., via WindowContext::request_close).
  • A fatal error or panic occurs in the WindowContext.
  • The underlying platform or display server (like X11) closes the window.
• Safety: Most Window methods return Result or become no-ops if the window has already been closed. Use Window::is_open() to check the current state.

To allow a baseview window to interact with its parent application (the host), you must implement the HostCallbacks trait. This is used to handle requests from the window to resize itself or to notify the host when the window is destroyed.

Implement the following methods:

• request_resize(new_size: WindowSize) -> Result<(), HandlerError>: Called when the window wants to change its size. Return Ok(()) to accept or an error to deny/cancel the resize.
• destroyed(): Called when the window is destroyed due to external factors (e.g., lost display connection or handler crash). The host should use this signal to close its parent window.

impl HostCallbacks for MyHost {
    fn request_resize(&mut self, new_size: WindowSize) -> Result<(), HandlerError> {
        // Handle resize logic here
        Ok(())
    }

    fn destroyed(&mut self) {
        // Clean up host resources
    }
}

To handle window events, rendering, and resizing in baseview, you must implement the WindowHandler trait. This trait provides three primary callbacks:

1. on_frame(): Called when the window needs to draw a new frame. If this returns an Err(HandlerError), the window is considered unable to render and will be closed.
2. resized(new_size: WindowSize): Called when the window size changes. If this returns an error, baseview will attempt to revert the window and its parent to the previous size as a best effort.
3. on_event(event: Event): Called when a window event occurs. It returns an EventStatus to indicate how the event should be handled.

impl WindowHandler for MyHandler {
    fn on_frame(&self) -> core::result::Result<(), HandlerError> {
        // Your rendering logic here
        Ok(())
    }

    fn resized(&self, new_size: WindowSize) -> core::result::Result<(), HandlerError> {
        // Handle resize logic
        Ok(())
    }

    fn on_event(&self, event: Event) -> EventStatus {
        // Handle input events
        EventStatus::Consumed
    }
}

When implementing a WindowHandler, you may encounter errors that are not directly related to Baseview's internal windowing logic. To return these errors from your handler, wrap them in a HandlerError.

HandlerError is a wrapper around a boxed dyn std::error::Error. It does not implement the std::error::Error trait itself, but it is designed to be easily converted into a Baseview Error using the ? operator or From implementation. This allows you to propagate your own application-specific errors up through the Baseview event loop.

Key methods:

• HandlerError::from_boxed(error: Box<dyn std::error::Error>): Creates a HandlerError from a boxed error.
• .source(): Returns the underlying error.
• .into_inner(): Consumes the HandlerError and returns the underlying Box<dyn std::error::Error>.

// Example of using HandlerError in a WindowHandler implementation
impl WindowHandler for MyHandler {
    fn handle_event(&mut self, event: Event) -> Result<(), HandlerError> {
        if let Some(data) = self.get_data() {
            // Convert a standard error into a HandlerError using the From implementation
            let custom_err = std::io::Error::new(std::io::ErrorKind::Other, "Something went wrong");
            return Err(custom_err.into());
        }
        Ok(())
    }
}