Trait WinHandler

pub trait WinHandler {
    // Required methods
    fn connect(&mut self, handle: &WindowHandle);
    fn prepare_paint(&mut self);
    fn paint(&mut self, piet: &mut Piet<'_>, invalid: &Region);
    fn as_any(&mut self) -> &mut dyn Any;

    // Provided methods
    fn size(&mut self, size: Size) { ... }
    fn scale(&mut self, scale: Scale) { ... }
    fn rebuild_resources(&mut self) { ... }
    fn command(&mut self, id: u32) { ... }
    fn save_as(&mut self, token: FileDialogToken, file: Option<FileInfo>) { ... }
    fn open_file(&mut self, token: FileDialogToken, file: Option<FileInfo>) { ... }
    fn open_files(&mut self, token: FileDialogToken, files: Vec<FileInfo>) { ... }
    fn key_down(&mut self, event: KeyEvent) -> bool { ... }
    fn key_up(&mut self, event: KeyEvent) { ... }
    fn acquire_input_lock(
        &mut self,
        token: TextFieldToken,
        mutable: bool,
    ) -> Box<dyn InputHandler> { ... }
    fn release_input_lock(&mut self, token: TextFieldToken) { ... }
    fn wheel(&mut self, event: &MouseEvent) { ... }
    fn zoom(&mut self, delta: f64) { ... }
    fn mouse_move(&mut self, event: &MouseEvent) { ... }
    fn mouse_down(&mut self, event: &MouseEvent) { ... }
    fn mouse_up(&mut self, event: &MouseEvent) { ... }
    fn mouse_leave(&mut self) { ... }
    fn timer(&mut self, token: TimerToken) { ... }
    fn got_focus(&mut self) { ... }
    fn lost_focus(&mut self) { ... }
    fn request_close(&mut self) { ... }
    fn destroy(&mut self) { ... }
    fn idle(&mut self, token: IdleToken) { ... }
}

App behavior, supplied by the app.

Many of the “window procedure” messages map to calls to this trait. The methods are non-mut because the window procedure can be called recursively; implementers are expected to use RefCell or the like, but should be careful to keep the lifetime of the borrow short.

Required Methods

fn connect(&mut self, handle: &WindowHandle)

Provide the handler with a handle to the window so that it can invalidate or make other requests.

This method passes the WindowHandle directly, because the handler may wish to stash it.

fn prepare_paint(&mut self)

Request the handler to prepare to paint the window contents. In particular, if there are any regions that need to be repainted on the next call to paint, the handler should invalidate those regions by calling WindowHandle::invalidate_rect or WindowHandle::invalidate.

fn paint(&mut self, piet: &mut Piet<'_>, invalid: &Region)

Request the handler to paint the window contents. invalid is the region in display points that needs to be repainted; painting outside the invalid region will have no effect.

fn as_any(&mut self) -> &mut dyn Any

Get a reference to the handler state. Used mostly by idle handlers.

Provided Methods

fn size(&mut self, size: Size)

Called when the size of the window has changed.

The size parameter is the new size in display points.

fn scale(&mut self, scale: Scale)

Called when the scale of the window has changed.

This is always called before the accompanying size.

fn rebuild_resources(&mut self)

Called when the resources need to be rebuilt.

Discussion: this function is mostly motivated by using GenericRenderTarget on Direct2D. If we move to DeviceContext instead, then it’s possible we don’t need this.

fn command(&mut self, id: u32)

Called when a menu item is selected.

fn save_as(&mut self, token: FileDialogToken, file: Option<FileInfo>)

Called when a “Save As” dialog is closed.

token is the value returned by WindowHandle::save_as. file contains the information of the chosen path, or None if the save dialog was cancelled.

fn open_file(&mut self, token: FileDialogToken, file: Option<FileInfo>)

Called when an “Open” dialog is closed.

token is the value returned by WindowHandle::open_file. file contains the information of the chosen path, or None if the save dialog was cancelled.

fn open_files(&mut self, token: FileDialogToken, files: Vec<FileInfo>)

Called when an “Open” dialog with multiple selection is closed.

token is the value returned by WindowHandle::open_file. files contains the information of the chosen paths, or None if the save dialog was cancelled.

fn key_down(&mut self, event: KeyEvent) -> bool

Called on a key down event.

Return true if the event is handled.

fn key_up(&mut self, event: KeyEvent)

Called when a key is released. This corresponds to the WM_KEYUP message on Windows, or keyUp(withEvent:) on macOS.

fn acquire_input_lock( &mut self, token: TextFieldToken, mutable: bool, ) -> Box<dyn InputHandler>

Take a lock for the text document specified by token.

All calls to this method must be balanced with a call to release_input_lock.

If mutable is true, the lock should be a write lock, and allow calling mutating methods on InputHandler. This method is called from the top level of the event loop and expects to acquire a lock successfully.

For more information, see the text input documentation.

fn release_input_lock(&mut self, token: TextFieldToken)

Release a lock previously acquired by acquire_input_lock.

fn wheel(&mut self, event: &MouseEvent)

Called on a mouse wheel event.

The polarity is the amount to be added to the scroll position, in other words the opposite of the direction the content should move on scrolling. This polarity is consistent with the deltaX and deltaY values in a web WheelEvent.

fn zoom(&mut self, delta: f64)

Called when a platform-defined zoom gesture occurs (such as pinching on the trackpad).

fn mouse_move(&mut self, event: &MouseEvent)

Called when the mouse moves.

fn mouse_down(&mut self, event: &MouseEvent)

Called on mouse button down.

fn mouse_up(&mut self, event: &MouseEvent)

Called on mouse button up.

fn mouse_leave(&mut self)

Called when the mouse cursor has left the application window

fn timer(&mut self, token: TimerToken)

Called on timer event.

This is called at (approximately) the requested deadline by a WindowHandle::request_timer() call. The token argument here is the same as the return value of that call.

fn got_focus(&mut self)

Called when this window becomes the focused window.

fn lost_focus(&mut self)

Called when this window stops being the focused window.

fn request_close(&mut self)

Called when the shell requests to close the window, for example because the user clicked the little “X” in the titlebar.

If you want to actually close the window in response to this request, call WindowHandle::close. If you don’t implement this method, clicking the titlebar “X” will have no effect.

fn destroy(&mut self)

Called when the window is being destroyed. Note that this happens earlier in the sequence than drop (at WM_DESTROY, while the latter is WM_NCDESTROY).

fn idle(&mut self, token: IdleToken)

Called when a idle token is requested by IdleHandle::schedule_idle() call.

Implementors