Skip to content

v0.3 - Host integration support

Choose a tag to compare

View all tags
@prokopyl prokopyl released this 02 Aug 20:47
v0.3
5bcc8b7

Breaking changes

Renamed WindowHandle to Window, and WindowOpenOptions to WindowSettings

This change makes the types' intent clearer, since the Window is not a simple handle but dictates the (longest possible) lifetime of the underlying platform window, and WindowSettings now apply to window creation time, which is now different to opening the window itself.

Unified window creation

The Window::open_parented and Window::open_blocking functions have been unified into a single function: Window::create. It only takes WindowSettings and the WindowHandler builder closure, and always returns a Window

Parenting has been moved into WindowSettings::with_parent, so it can be set on any window.
Blocking behaviour has been moved into Window::run_until_closed, which runs an event loop and blocks the thread until the window is closed.

This means parenting and blocking are now orthogonal features: you can now open floating windows without blocking the thread, or block the thread on parenting windows.

let window_open_options = WindowSettings::new()
    .with_size(LogicalSize::new(256, 256))
    .with_parent(&parent_window)
    .with_title("baseview child");

let child_window = Window::create(window_open_options, ChildWindowHandler::new)?;

Creating a window no longer immediately opens it

This is done to allow further configuration by hosts after the window is created, without incurring potentially expensive additional operations by the window manager.

In order to actually show the window on screen, you have to use the new Window::show method.
Alternatively the new Window::run_until_closed method will automatically show the window if it isn't already.

Window Handler creation closure now returns a Result

This makes the window handler creation properly fallible, without having to resort to panicking.

When the closure fails, all already-created resources are cleanly destroyed, and the error is propagated back to Window::create (which also returns a result).

OpenGL get_proc_address now takes &CStr

This is done to avoid an useless and potentially fallible double-conversion between &str and &CStr.
Most GL libraries (such as glow) provide more straightforward loader function helpers that take &CStr and are able to take advantage of this.

Alternatively, the GlContext::get_proc_address_from_str method has been added, which implements the previous behaviour, if needed.

WindowScalePolicy has been removed

Baseview will now always take the global scaling user setting into account, if the platform is able to provide it.
If it can't be found (e.g. in older Windows versions or some weird X11 configurations), you can use the new Window::suggest_fallback_scale_factor method to provide a fallback.

New feature Highlights

Host integration

This release introduces a new Host type, which is a set of handlers for various callback types. Baseview will use those callbacks to notify or negotiate directly with the host that controls the parent window.

For now, three callbacks can be implemented, but more could come in the future:

  • HostCallbacks::request_resize: called when the child window is being resized, and the parent window needs to adjust to accommodate it;
  • HostCallbacks::destroyed: called when the child window has been destroyed, for reasons other than the host requesting it;
  • (used on X11 only) HostMainThreadCaller::call_main_thread: since the X11 platform relies on a separate window thread, this is used internally by baseview to plug into an existing thread notification system (usually the host's) to then trigger the other main-thread callbacks using the Window::host_main_thread_callback method.

You can take a look at the plugin_clack example for a practical example usage of these new APIs.

Proper Error Handling

Baseview now has way fewer panics, and now properly returns errors on most operations.
It also allows most user-provided callbacks (including most notably the WindowHandler) to return any kind of errors, and baseview will properly handle them (see the WindowHandler docs for more details on how exactly).

It does this by introducing two error types:

Error is a monolithic, opaque error type that can be returned from all fallible window operations. It mostly consists of platform-dependent error types, and provides Display and std::error::Error implementations to help you figure out what went wrong.

Handler is a type that does not implement std::error::Error, but instead implements From<T> for any T: std::error::Error. It is returned by all fallible WindowHandler trait methods, which enables you to use From or the ? operator on any error type to propagate it and let baseview handle it.

Delayed parented window creation

The WindowSettings type has a new wait_for_parent field, which when set, delays the actual window creation until the first set_parent call.

This allows better integration with e.g. the CLAP API, where the create call needs to initialize some state (e.g. for get_size) before set_parent is called.

Optional tracing support

For errors that cannot be returned to the user via Results (such as ones from operations occurring in platform callbacks), a new tracing feature can be enabled.

This will add tracing as a dependency, and baseview will use it to log any errors or warnings that it encounters.

If the feature is not enabled, all of these warnings are no-op'd and compiled away.

New actions on the Window type

The Window type gained new methods, allowing you to perform some actions from outside the WindowHandler that manages the window:

  • Window::size returns the WindowSize in both logical and physical coordinates;
  • Window::resize requests a window resize;
  • Window::suggest_fallback_scale_factor submits a scale factor to use if baseview couldn't get one from the platform. It is ignored if the platform was able to provide one (which is always the case on macOS).
  • Window::close now consumes the handle, and now identical to just dropping the Window itself.
  • Window::set_parent enables you to set a parent window after window creation. If the window already had a parent, it will be re-parented. If not, the window will seamlessly turn from a floating window to a parented window.
  • Window::show and Window::hide to show/hide the window.

And more to come! 🙂

What's Changed

Full Changelog: v0.2.2...v0.3

Contributors

prokopyl and BillyDM
Assets 2
Loading