Handler API

This page is for querying the main public APIs of flor::view::handler and flor::view::builder::EventBuilder. For usage instructions, see External Events.

Imports

use flor::view::builder::EventBuilder;
use flor::view::handler::*;
use flor::view::ViewId;

use flor::base::platform::{
    HandleResult, KeyCode, KeyState, MousePosition, ScrollAxis,
};

After enabling drag-drop or theme features, you will also need these types:

use flor::base::platform::{DragData, DragFormat, DropEffect};
use flor::base::platform::ThemeMode;

`EventBuilder`

EventBuilder is implemented for all V: ViewIdentity. All methods save the handler and return Self for chain calls. Normal views, ViewBox, and values returned as impl IntoView can all keep using these methods.

pub trait EventBuilder {
    fn on_mouse_move<Args>(self, handler: impl IntoEventHandler<OnMouseMoveHandler, Args>) -> Self;
    fn on_double_click<Args>(self, handler: impl IntoEventHandler<OnDoubleClickHandler, Args>) -> Self;
    fn on_click<Args>(self, handler: impl IntoEventHandler<OnClickHandler, Args>) -> Self;
    fn on_button_down<Args>(self, handler: impl IntoEventHandler<OnButtonDownHandler, Args>) -> Self;
    fn on_button_up<Args>(self, handler: impl IntoEventHandler<OnButtonUpHandler, Args>) -> Self;

    fn on_right_button_double_click<Args>(
        self,
        handler: impl IntoEventHandler<OnRightButtonDoubleClickHandler, Args>,
    ) -> Self;
    fn on_right_button_click<Args>(self, handler: impl IntoEventHandler<OnRightButtonClickHandler, Args>) -> Self;
    fn on_right_button_down<Args>(self, handler: impl IntoEventHandler<OnRightButtonDownHandler, Args>) -> Self;
    fn on_right_button_up<Args>(self, handler: impl IntoEventHandler<OnRightButtonUpHandler, Args>) -> Self;

    fn on_middle_button_double_click<Args>(
        self,
        handler: impl IntoEventHandler<OnMiddleButtonDoubleClickHandler, Args>,
    ) -> Self;
    fn on_middle_button_down<Args>(self, handler: impl IntoEventHandler<OnMiddleButtonDownHandler, Args>) -> Self;
    fn on_middle_button_up<Args>(self, handler: impl IntoEventHandler<OnMiddleButtonUpHandler, Args>) -> Self;

    fn on_context_menu<Args>(self, handler: impl IntoEventHandler<OnContextMenuHandler, Args>) -> Self;

    fn on_key_down<Args>(self, handler: impl IntoEventHandler<OnKeyDownHandler, Args>) -> Self;
    fn on_key_up<Args>(self, handler: impl IntoEventHandler<OnKeyUpHandler, Args>) -> Self;

    fn on_mouse_enter<Args>(self, handler: impl IntoEventHandler<OnMouseEnterHandler, Args>) -> Self;
    fn on_mouse_leave<Args>(self, handler: impl IntoEventHandler<OnMouseLeaveHandler, Args>) -> Self;
    fn on_focus<Args>(self, handler: impl IntoEventHandler<OnFocusHandler, Args>) -> Self;
    fn on_blur<Args>(self, handler: impl IntoEventHandler<OnBlurHandler, Args>) -> Self;
    fn on_create<Args>(self, handler: impl IntoEventHandler<OnCreateHandler, Args>) -> Self;
    fn on_destroy<Args>(self, handler: impl IntoEventHandler<OnDestroyHandler, Args>) -> Self;

    fn on_resize<Args>(self, handler: impl IntoEventHandler<OnResizeHandler, Args>) -> Self;
    fn on_close_requested<Args>(self, handler: impl IntoEventHandler<OnCloseRequestedHandler, Args>) -> Self;
    fn on_work_area_changed<Args>(self, handler: impl IntoEventHandler<OnWorkAreaChangedHandler, Args>) -> Self;
    fn on_wheel_settings_changed<Args>(
        self,
        handler: impl IntoEventHandler<OnWheelSettingsChangedHandler, Args>,
    ) -> Self;
    fn on_dpi_change<Args>(self, handler: impl IntoEventHandler<OnDpiChangeHandler, Args>) -> Self;

    #[cfg(feature = "theme-change")]
    fn on_theme_changed<Args>(self, handler: impl IntoEventHandler<OnThemeChangedHandler, Args>) -> Self;

    #[cfg(feature = "drag-drop")]
    fn on_drag_enter<Args>(self, handler: impl IntoEventHandler<OnDragEnterHandler, Args>) -> Self;
    #[cfg(feature = "drag-drop")]
    fn on_drag_over<Args>(self, handler: impl IntoEventHandler<OnDragOverHandler, Args>) -> Self;
    #[cfg(feature = "drag-drop")]
    fn on_drag_leave<Args>(self, handler: impl IntoEventHandler<OnDragLeaveHandler, Args>) -> Self;
    #[cfg(feature = "drag-drop")]
    fn on_drop<Args>(self, handler: impl IntoEventHandler<DropHandler, Args>) -> Self;
}

`IntoEventHandler`

IntoEventHandler<T, Args> is the conversion entry used by event builders. It converts closures, normal functions, associated functions, method items, or generic functions with already specified generic arguments into the target handler wrapper type.

pub trait IntoEventHandler<T, Args> {
    fn into_event_handler(self) -> T;
}

The conversion has two layers:

Layer	Mechanism
Full arguments	The handler wrapper type implements `From<F>`, and `IntoEventHandler<T, FullArgs>` calls that `From` conversion through `F: Into<T>`
Simplified arguments	`IntoEventHandler<T, Args>` has implementations that fill omitted arguments for forms such as no arguments, `ViewId` only, or without `ViewId`

So the full-argument form is driven by From conversion, and Event Builder uses IntoEventHandler<T, Args> to unify different parameter forms into one entry. Args is a compile-time marker used to distinguish parameter forms; Rust usually infers it when you call .on_click(...), .on_key_down(...), and similar methods.

For example, the underlying type of on_click is MouseHandler. All four forms below can convert into OnClickHandler:

view.on_click(|view_id, key_state, mouse_position| { /* full arguments */ });
view.on_click(|| { /* does not need event parameters */ });
view.on_click(|view_id| { /* only cares about the view */ });
view.on_click(|key_state, mouse_position| { /* omits ViewId */ });

Handler alias events whose complete parameter list is only ViewId, such as on_mouse_enter, on_mouse_leave, on_create, on_destroy, and on_resize, do not have an "omit ViewId but keep event data" form. They only support full arguments and no arguments.

Functions and method items participate in the same conversion as long as they satisfy the corresponding Fn(...) + Send + Sync + 'static signature:

fn clicked(view_id: ViewId) {
    println!("{view_id}");
}

struct Actions;

impl Actions {
    fn open<const SLOT: usize>(view_id: ViewId) {
        println!("open {SLOT}: {view_id}");
    }
}

view.on_click(clicked);
view.on_click(Actions::open::<1>);

If you accept and forward handlers in your own view wrapper, do not go back to impl Into<OnClickHandler>. Keep the Args generic so callers can still use full arguments, no arguments, ViewId only, or without ViewId:

fn accept_click<Args>(handler: impl IntoEventHandler<OnClickHandler, Args>) -> OnClickHandler {
    handler.into_event_handler()
}

Current Dispatch Status

API	Current Status
`on_mouse_move`	Dispatched. Target is the mouse-capturing view or current hover view
`on_mouse_enter` / `on_mouse_leave`	Dispatched. Triggered when hover target changes
`on_button_down` / `on_button_up`	Dispatched. Left button down/up
`on_click`	Dispatched. Synthesized when left button down/up hit the same view
`on_double_click`	Dispatched. Left button double click
`on_right_button_down` / `on_right_button_up`	Dispatched. Right button down/up
`on_right_button_click`	Dispatched. Synthesized when right button down/up hit the same view
`on_right_button_double_click`	Dispatched. Right button double click
`on_middle_button_down` / `on_middle_button_up`	Dispatched. Middle button down/up
`on_middle_button_double_click`	Dispatched. Middle button double click
`on_key_down` / `on_key_up`	Dispatched. Target is current focus view
`on_focus` / `on_blur`	Dispatched. Triggered by focus manager
`on_create`	Dispatched. Triggered after window creates view tree
`on_wheel_settings_changed`	Dispatched. Current mouse wheel messages go through this handler
`on_drag_enter` / `on_drag_over` / `on_drag_leave` / `on_drop`	Dispatched, requires `drag-drop` feature
`on_context_menu`	Has binding slot, currently no external dispatch entry in source
`on_destroy`	Has binding slot, currently no external dispatch entry in source
`on_resize`	Has binding slot, current Resize only updates layout and render size, no external handler call
`on_close_requested`	Has binding slot, current close request doesn't call external handler
`on_work_area_changed`	Has binding slot, current window bus implementation is empty
`on_dpi_change`	Has binding slot, current DPI message only updates renderer, units and layout, no external handler call
`on_theme_changed`	Has binding slot, requires `theme-change` feature, current window bus implementation is empty

`ViewHandler`

ViewHandler is a set of handler slots for each ViewId. Application code usually writes to these slots through EventBuilder, without directly manipulating ViewHandler.

#[derive(Default)]
pub struct ViewHandler {
    pub on_mouse_move_handler: Option<OnMouseMoveHandler>,
    pub on_double_click_handler: Option<OnDoubleClickHandler>,
    pub on_click_handler: Option<OnClickHandler>,
    pub on_button_down_handler: Option<OnButtonDownHandler>,
    pub on_button_up_handler: Option<OnButtonUpHandler>,

    pub on_right_button_double_click_handler: Option<OnRightButtonDoubleClickHandler>,
    pub on_right_button_click_handler: Option<OnRightButtonClickHandler>,
    pub on_right_button_down_handler: Option<OnRightButtonDownHandler>,
    pub on_right_button_up_handler: Option<OnRightButtonUpHandler>,

    pub on_middle_button_double_click_handler: Option<OnMiddleButtonDoubleClickHandler>,
    pub on_middle_button_down_handler: Option<OnMiddleButtonDownHandler>,
    pub on_middle_button_up_handler: Option<OnMiddleButtonUpHandler>,

    pub on_context_menu_handler: Option<OnContextMenuHandler>,

    pub on_key_down_handler: Option<OnKeyDownHandler>,
    pub on_key_up_handler: Option<OnKeyUpHandler>,

    pub on_mouse_enter_handler: Option<OnMouseEnterHandler>,
    pub on_mouse_leave_handler: Option<OnMouseLeaveHandler>,
    pub on_focus_handler: Option<OnFocusHandler>,
    pub on_blur_handler: Option<OnBlurHandler>,
    pub on_create_handler: Option<OnCreateHandler>,
    pub on_destroy_handler: Option<OnDestroyHandler>,

    pub on_tooltip_show_handler: Option<OnTooltipShowHandler>,
    pub on_tooltip_hide_handler: Option<OnTooltipHideHandler>,

    pub on_resize_handler: Option<OnResizeHandler>,
    pub on_close_requested_handler: Option<OnCloseRequestedHandler>,
    pub on_work_area_changed_handler: Option<OnWorkAreaChangedHandler>,
    pub on_wheel_settings_changed_handler: Option<OnWheelSettingsChangedHandler>,
    pub on_dpi_change_handler: Option<OnDpiChangeHandler>,

    #[cfg(feature = "theme-change")]
    pub on_theme_changed_handler: Option<OnThemeChangedHandler>,

    #[cfg(feature = "drag-drop")]
    pub on_drag_enter_handler: Option<OnDragEnterHandler>,
    #[cfg(feature = "drag-drop")]
    pub on_drag_over_handler: Option<OnDragOverHandler>,
    #[cfg(feature = "drag-drop")]
    pub on_drag_leave_handler: Option<OnDragLeaveHandler>,
    #[cfg(feature = "drag-drop")]
    pub on_drop_handler: Option<DropHandler>,
}

Handler Wrapper Types

All handler wrapper types implement From<F> for the full parameter signature, where F is a closure or function with the corresponding signature and satisfies Send + Sync + 'static. Event Builder also supports several simplified parameter forms through IntoEventHandler, so user code usually passes closures directly without manually constructing wrapper types.

`Handler`

pub struct Handler(pub Arc<dyn Fn(ViewId) + Send + Sync + 'static>);

Used for events that only need ViewId.

Accepted forms:

Form	Example
Full arguments	`\|view_id\| { ... }`
No arguments	`\|\| { ... }`

`MouseHandler`

pub struct MouseHandler(
    pub Arc<dyn Fn(ViewId, KeyState, MousePosition) + Send + Sync + 'static>,
);

Used for mouse move, click, button down, button up, double click and similar events.

Accepted forms:

Form	Example
Full arguments	`\|view_id, key_state, mouse_position\| { ... }`
No arguments	`\|\| { ... }`
`ViewId` only	`\|view_id\| { ... }`
Without `ViewId`	`\|key_state, mouse_position\| { ... }`

`KeyHandler`

pub struct KeyHandler(
    pub Arc<
        dyn Fn(ViewId, KeyCode, bool, bool, bool) -> HandleResult
            + Send
            + Sync
            + 'static,
    >,
);

Parameters are ViewId, KeyCode, is_alt, is_ctrl, is_shift in order.

Accepted forms:

Form	Example
Full arguments	`\|view_id, code, is_alt, is_ctrl, is_shift\| -> HandleResult { ... }`
No arguments	`\|\| -> HandleResult { ... }`
`ViewId` only	`\|view_id\| -> HandleResult { ... }`
Without `ViewId`	`\|code, is_alt, is_ctrl, is_shift\| -> HandleResult { ... }`

`FocusHandler`

pub struct FocusHandler(
    pub Arc<dyn Fn(ViewId, u16) + Send + Sync + 'static>,
);

The second parameter is the virtual focus index.

Accepted forms:

Form	Example
Full arguments	`\|view_id, focus_index\| { ... }`
No arguments	`\|\| { ... }`
`ViewId` only	`\|view_id\| { ... }`
Without `ViewId`	`\|focus_index\| { ... }`

`OnWheelSettingsChangedHandler`

pub struct OnWheelSettingsChangedHandler(
    pub Arc<
        dyn Fn(ViewId, ScrollAxis, f32, KeyState, MousePosition)
            + Send
            + Sync
            + 'static,
    >,
);

Parameters are ViewId, scroll direction, scroll amount, key state, mouse position in order.

Accepted forms:

Form	Example
Full arguments	`\|view_id, axis, delta, key_state, mouse_position\| { ... }`
No arguments	`\|\| { ... }`
`ViewId` only	`\|view_id\| { ... }`
Without `ViewId`	`\|axis, delta, key_state, mouse_position\| { ... }`

`OnDpiChangeHandler`

pub struct OnDpiChangeHandler(
    pub Arc<dyn Fn(ViewId, f32, f32) + Send + Sync + 'static>,
);

The second and third parameters are dpi_x and dpi_y.

Accepted forms:

Form	Example
Full arguments	`\|view_id, dpi_x, dpi_y\| { ... }`
No arguments	`\|\| { ... }`
`ViewId` only	`\|view_id\| { ... }`
Without `ViewId`	`\|dpi_x, dpi_y\| { ... }`

`OnThemeChangedHandler`

Requires theme-change feature.

pub struct OnThemeChangedHandler(
    pub Arc<dyn Fn(ViewId, ThemeMode) + Send + Sync + 'static>,
);

Accepted forms:

Form	Example
Full arguments	`\|view_id, theme_mode\| { ... }`
No arguments	`\|\| { ... }`
`ViewId` only	`\|view_id\| { ... }`
Without `ViewId`	`\|theme_mode\| { ... }`

`DragEnterOverHandler`

Requires drag-drop feature.

pub struct DragEnterOverHandler(
    pub Arc<
        dyn Fn(ViewId, KeyState, MousePosition, &[DragFormat], &mut DropEffect)
            + Send
            + Sync
            + 'static,
    >,
);

Used for on_drag_enter and on_drag_over.

Accepted forms:

Form	Example
Full arguments	`\|view_id, key_state, mouse_position, formats, effect\| { ... }`
No arguments	`\|\| { ... }`
`ViewId` only	`\|view_id\| { ... }`
Without `ViewId`	`\|key_state, mouse_position, formats, effect\| { ... }`

`DropHandler`

Requires drag-drop feature.

pub struct DropHandler(
    pub Arc<
        dyn Fn(ViewId, KeyState, MousePosition, &DragData, &mut DropEffect)
            + Send
            + Sync
            + 'static,
    >,
);

Used for on_drop.

Accepted forms:

Form	Example
Full arguments	`\|view_id, key_state, mouse_position, data, effect\| { ... }`
No arguments	`\|\| { ... }`
`ViewId` only	`\|view_id\| { ... }`
Without `ViewId`	`\|key_state, mouse_position, data, effect\| { ... }`

Type Aliases

Mouse Events

Alias	Underlying Type
`OnMouseMoveHandler`	`MouseHandler`
`OnDoubleClickHandler`	`MouseHandler`
`OnClickHandler`	`MouseHandler`
`OnButtonDownHandler`	`MouseHandler`
`OnButtonUpHandler`	`MouseHandler`
`OnRightButtonDoubleClickHandler`	`MouseHandler`
`OnRightButtonClickHandler`	`MouseHandler`
`OnRightButtonDownHandler`	`MouseHandler`
`OnRightButtonUpHandler`	`MouseHandler`
`OnMiddleButtonDoubleClickHandler`	`MouseHandler`
`OnMiddleButtonDownHandler`	`MouseHandler`
`OnMiddleButtonUpHandler`	`MouseHandler`
`OnContextMenuHandler`	`MouseHandler`

Currently there is no OnMiddleButtonClickHandler.

Keyboard Events

Alias	Underlying Type
`OnKeyDownHandler`	`KeyHandler`
`OnKeyUpHandler`	`KeyHandler`

View and Lifecycle Events

Alias	Underlying Type
`OnMouseEnterHandler`	`Handler`
`OnMouseLeaveHandler`	`Handler`
`OnFocusHandler`	`FocusHandler`
`OnBlurHandler`	`FocusHandler`
`OnCreateHandler`	`Handler`
`OnDestroyHandler`	`Handler`

Alias	Underlying Type
`OnTooltipShowHandler`	`MouseHandler`
`OnTooltipHideHandler`	`Handler`

Currently EventBuilder does not expose chain binding methods for tooltip.

Window Events

Alias	Underlying Type
`OnResizeHandler`	`Handler`
`OnCloseRequestedHandler`	`Handler`
`OnWorkAreaChangedHandler`	`Handler`
`OnWheelSettingsChangedHandler`	Independent wrapper type
`OnDpiChangeHandler`	Independent wrapper type
`OnThemeChangedHandler`	Independent wrapper type, requires `theme-change` feature

Drag-Drop Events

Requires drag-drop feature.

Alias	Underlying Type
`OnDragEnterHandler`	`DragEnterOverHandler`
`OnDragOverHandler`	`DragEnterOverHandler`
`OnDragLeaveHandler`	`Handler`
`DropHandler`	Independent wrapper type

Parameter Descriptions

Type	Description
`ViewId`	ID of the target view that triggered the event
`KeyState`	Mouse button and modifier key state
`MousePosition`	Mouse coordinates. Regular mouse hit events use target view local coordinates; wheel and drag-drop currently use window client area coordinates
`KeyCode`	Key enumeration. Common keys include letters, numbers, arrow keys, function keys, `Enter`, `Escape`, `Tab`, `Backspace`, `Space`, `Delete`
`HandleResult`	Keyboard event handling result, `Handled` means processed, `Default` means default processing
`ScrollAxis`	`Vertical` or `Horizontal`
`DropEffect`	Drag-drop feedback effect, commonly `None`, `Copy`, `Move`, `Link`
`DragFormat`	Data formats available during drag enter/over phase
`DragData`	Actual data passed during drop phase

#Handler API

#Imports

#EventBuilder

#IntoEventHandler

#Current Dispatch Status

#ViewHandler

#Handler Wrapper Types

#Handler

#MouseHandler

#KeyHandler

#FocusHandler

#OnWheelSettingsChangedHandler

#OnDpiChangeHandler

#OnThemeChangedHandler

#DragEnterOverHandler

#DropHandler

#Type Aliases

#Mouse Events

#Keyboard Events

#View and Lifecycle Events

#Tooltip Events

#Window Events

#Drag-Drop Events

#Parameter Descriptions

Handler API

Imports

`EventBuilder`

`IntoEventHandler`

Current Dispatch Status

`ViewHandler`

Handler Wrapper Types

`Handler`

`MouseHandler`

`KeyHandler`

`FocusHandler`

`OnWheelSettingsChangedHandler`

`OnDpiChangeHandler`

`OnThemeChangedHandler`

`DragEnterOverHandler`

`DropHandler`

Type Aliases

Mouse Events

Keyboard Events

View and Lifecycle Events

Tooltip Events

Window Events

Drag-Drop Events

Parameter Descriptions