Event Handling
Containers can respond to mouse events for user interaction.
Click Events
extern crate guido;
use guido::prelude::*;
fn main() {
container()
.on_click(|| {
println!("Clicked!");
})
;
}
Click events fire when the mouse button is pressed and released within the container bounds, where it shows: a release over a sibling drawn on top of it, or over a part a scrolling parent clips away, clicks nothing.
Double Clicks
extern crate guido;
use guido::prelude::*;
fn main() {
let select = move || {};
let open = move || {};
container()
.on_click(select)
.on_double_click(open)
;
}
on_double_click fires on the release of the second click, as the web’s
dblclick does. on_click still fires for both clicks, so the first click of
a double click selects and the second opens. A click is the second of a pair
when it is the same button, within 400 ms and 5 px of the first, with no drag
between.
Every press carries its place in the run: Event::MouseDown’s count is 1
for a single click, 2 for the second of a double click, 3 for a triple, so a
widget that wants a triple click reads it there. A finger always presses 1.
With Signal Updates
extern crate guido;
use guido::prelude::*;
fn main() {
let count = create_signal(0);
container()
.on_click(move || {
count.update(|c| *c += 1);
})
.child(text(move || format!("Clicks: {}", count.get())))
;
}
Hover Events
extern crate guido;
use guido::prelude::*;
fn main() {
container()
.on_hover(|hovered| {
if hovered {
println!("Mouse entered");
} else {
println!("Mouse left");
}
})
;
}
The callback receives a boolean indicating hover state.
When one pointer move leaves some containers and enters others, every
on_hover(false) it causes is called before any on_hover(true). Leaves go
from the innermost container outward, enters from the outermost inward, so the
container the pointer left hears first and the one it reached hears last. A
container holding both, which the pointer never left, hears nothing. The order
is the same whichever way the pointer moved and whichever sibling is drawn on
top, and it is the one browsers, Flutter, GTK and Qt give.
on_pointer_move is called after all of them, so a container hears the
pointer enter it before it hears the pointer move over it, and the container
the pointer left has already heard so, as in a browser.
The hover state that when_hovered reads has already changed by the time
any of these callbacks runs.
A container hidden or disabled while the pointer is on it ends the hover and
the press of everything in it, itself included: on_hover(false) is called,
and a press that was being held is dropped without a click, so nothing comes
back hovered or pressed when it is shown or enabled again. That happens at the
next pointer event to reach it, or once a frame has been drawn after hiding it
moved something on the surface, as the next paragraph says — not at the instant
it is hidden.
What is under a pointer that stays still can change: a wheel step, a touchpad’s
glide or the keyboard scrolls a list, a row above grows, a child is built in
place of the one that was there. Once a frame has been drawn after something
like that, the hover and the cursor are worked out again where the pointer is,
so the row that went hears on_hover(false) and the one now under the pointer
on_hover(true), without waiting for the pointer to move. It is worked out once
a frame, where the pointer is then: a row that a single wheel step carries
right past the pointer is never under it when the hover is worked out, and
hears nothing. A child removed with no exit hears nothing as it goes; what it uncovers does.
on_pointer_move hears none of this: the pointer did not move. Nor does a
hover style that draws the box elsewhere count — when_hovered drawing it
lifted or scaled — or a box near the pointer’s edge would take its hover back
on one frame and give it back on the next. It is still worked out where the
box is drawn, so a layout elsewhere on the surface can take the hover from a
lifted box whose pointer rests in the strip the lift uncovered. One that
changes the size does count, as any layout does, and under a pointer resting
near the edge it flickers that way: a label whose font_size shrinks on hover,
or an on_hover that makes its container smaller or shows something on top of
it. A CSS :hover that resizes its element does the same. An animation that
only draws a box elsewhere is not followed either: a box that slides, or that
moves or enters by a transform, takes the hover when the pointer next moves,
and so does a sibling that only comes to be drawn on top. One that changes a
size is a layout, and is followed as one. With a button held nothing is
worked out again, since a move then would carry on as a drag; the release of
the mouse button does it, unless its click closes the surface. A finger lifted
is over nothing. A surface that changed size works nothing out again until the
next pointer event says where the pointer is.
Hover with State Layer
For visual hover effects, use when_hovered instead:
// not compiled: `log` is the caller's crate, not one the book is
// compiled against.
extern crate guido;
use guido::prelude::*;
fn main() {
// Preferred for visual effects
container().when_hovered(|s| s.lighter(0.1));
// Use on_hover for side effects only
container().on_hover(|hovered| {
log::info!("Hover changed: {}", hovered);
})
;
}
Other Buttons and Keys
extern crate guido;
use guido::prelude::*;
fn main() {
let close = move || {};
container()
.on_click(|| println!("left"))
.on_right_click(|| println!("right"))
.on_middle_click(|| println!("middle"))
.on_key_down(move |key, _mods, _repeat| {
if key == Key::Escape {
close();
return EventResponse::Handled;
}
EventResponse::Ignored
})
;
}
on_key_down fires while the surface has keyboard focus — a layer surface
with KeyboardInteractivity set, or a popup holding a grab.
A key is a Key: a character, Key::Char, or one of the named keys — Enter,
Tab, Escape, Backspace, Delete, the arrows, Home and End, Key::PageUp,
Key::PageDown, and the function keys Key::F(1) to Key::F(12). The
keypad’s Enter, and with NumLock off its arrows, Home, End, Page Up, Page Down
and Delete, are the same keys as the main block’s. A text input takes neither Up, Down, Page Up,
Page Down nor a function key, so they reach the listener around it — unless a
scroller stands between them, which scrolls with the arrows, Page Up, Page
Down, Home and End while it can move: see
What Moves It.
It answers whether it took the key, as a widget’s event does. Handled stops
the key there; Ignored lets it go on to the next container listening, and
then to what the key does by default — Tab moving the focus, under
Moving the Focus with Tab. A listener that answers
Handled for every key keeps Tab from ever moving the focus out of it.
A widget with the focus — a text input you clicked into — hears a key first,
and the containers around it after. on_key_down hears what nothing focused
took, so Escape still closes a menu while its search field has the focus, and
it hears it with nothing focused at all. Where two containers both declare it,
the inner one hears the key first; where they stand side by side, the earlier
one. The other hears it only when the first lets it through.
A held key arrives again at the compositor’s repeat rate, and each repeat is
an ordinary key-down whose third argument is true. Text editing wants every
one; something that should happen once per press returns early on a repeat:
extern crate guido;
use guido::prelude::*;
fn main() {
let activate = move || {};
container().on_key_down(move |key, _mods, repeat| {
if key != Key::Enter {
return EventResponse::Ignored;
}
if !repeat {
activate();
}
EventResponse::Handled
})
;
}
A widget of your own reads the same flag as the repeat field of
Event::KeyDown.
on_key_up hears a key being released, with the modifiers held as it went up,
along the same route as on_key_down. That is where a button answers Space:
the press shows it pressed, and the release activates it, so moving away before
letting go abandons it.
extern crate guido;
use guido::prelude::*;
fn main() {
let activate = move || {};
let held = create_signal(false);
container()
.on_key_down(move |key, _mods, _repeat| {
if key != Key::Char(' ') {
return EventResponse::Ignored;
}
held.set(true);
EventResponse::Handled
})
.on_key_up(move |key, _mods| {
if key == Key::Char(' ') && held.get_untracked() {
held.set(false);
activate();
return EventResponse::Handled;
}
EventResponse::Ignored
})
;
}
A release is not paired with its press. A text input that took a key’s press lets its release through, so a container around it or listening beside it can hear a key go up that it never heard go down — which is why the sample above remembers the press itself.
Hearing a Key Before the Focused Widget
The field has the key first, so a key it uses never reaches the containers
around it: a text input takes Left and Right to move its caret. A launcher
whose search field keeps the focus while the arrows move a selection needs
those keys before the field sees them. on_key_down_capture hears a key on its
way down to the focused widget instead of on its way back up:
extern crate guido;
use guido::prelude::*;
fn main() {
let query = create_signal(String::new());
let selected = create_signal(0usize);
container()
.on_key_down_capture(move |key, _mods, _repeat| match key {
Key::Left => {
selected.update(|s| *s = s.saturating_sub(1));
EventResponse::Handled
}
Key::Right => {
selected.update(|s| *s += 1);
EventResponse::Handled
}
_ => EventResponse::Ignored,
})
.child(text_input(query).autofocus())
;
}
Capture listeners hear the key from the outermost container in. Handled
stops it there: the field never sees it, no on_key_down hears it, and a Tab
taken this way does not move the focus. Ignored lets it go on to the next
capture listener inside, then the focused widget, then the on_key_down
listeners on the way back up — so the characters above still type, and Up and
Down, which the field lets through, still reach an on_key_down on the same
container. A focused container hears its own capture before its own
on_key_down.
With nothing focused, a key goes to the containers listening for it as
before, and a capture listener hears it on the way to them, before the
listeners inside it. on_key_up_capture does the same for releases.
Moving the Focus with Tab
Tab moves the keyboard focus to the next text input on the surface, and
Shift+Tab to the one before. A container joins them by declaring
focusable(true):
extern crate guido;
use guido::prelude::*;
fn main() {
let open = move || {};
container()
.focusable(true)
.when_focused(|s| s.outline(2.0, Color::WHITE, 2.0))
.on_key_down(move |key, _mods, _repeat| {
if key == Key::Enter {
open();
return EventResponse::Handled;
}
EventResponse::Ignored
})
.child(text("Settings"))
;
}
Tab stops at it, a press inside it takes the focus — as tabindex="0" does on
the web — and with the focus there its when_focused lights up and its
on_key_down hears the keys first. The press is not consumed: a clickable row
around it still gets its click. A press that something inside it took — a
button in the card — stays that button’s, and the focus does not move. A container that is not focusable can still be
given the focus by a widget ref;
it is only not a place Tab stops.
Moving the focus is what a Tab does when nothing took it: the
focused widget hears it first, then the containers around it, then the
listeners, and only a Tab all of them let through moves the focus. A widget
that wants Tab for itself — an editor inserting a tab character — answers
Handled, and the focus stays where it is.
The order is reading order: top to bottom by where each stop was laid out, then left to right, as GTK orders it. It follows what is on screen, so a list reordered by key is walked in the order it is shown. At the last stop Tab goes round to the first, and Shift+Tab at the first to the last. With nothing focused, Tab takes the first and Shift+Tab the last.
A stop inside a hidden or disabled container is passed over, and so is one playing its exit. Tab stays on the surface holding the keyboard: in a popup, it goes round the popup’s own stops.
Tab with Ctrl, Alt or the logo key held does not move the focus; that is left to whatever shortcut it is.
Latched Modifiers
The Modifiers a key event carries describe that keystroke, which is what a
shortcut needs. Caps lock is a different question: it is latched, so it stays
on with nothing pressed, and something on screen may need to say so before
anything has been typed — a password field warning that what goes in will be
upper case.
That cannot be answered from a key event. The compositor sends the modifier update after the key that toggled it, so the press of caps lock reports the state it had before. Read the signal instead:
extern crate guido;
use guido::prelude::*;
fn main() {
container().child(move || {
keyboard_modifiers()
.get()
.caps_lock
.then(|| text("Caps lock is on"))
})
;
}
Everything is false until the compositor sends the first update, which it does when a surface takes keyboard focus.
Scroll Events
extern crate guido;
use guido::prelude::*;
fn main() {
container()
.on_scroll(|dx, dy, source| {
println!("Scroll: dx={}, dy={}", dx, dy);
})
;
}
Parameters:
dx- Horizontal scroll amountdy- Vertical scroll amountsource- Scroll source (wheel, touchpad)
Scroll with Signal
extern crate guido;
use guido::prelude::*;
fn main() {
let offset = create_signal(0.0f32);
container()
.on_scroll(move |_dx, dy, _source| {
offset.update(|o| *o += dy);
})
.child(text(move || format!("Offset: {:.0}", offset.get())))
;
}
Touch Input
Touchscreens work out of the box: the first finger down drives the same
pointer pipeline as the mouse, so on_click, when_hovered,
when_pressed (including ripples), and scroll all respond to touch. A
tap is a click; lifting the finger clears hover state. No code changes
are needed.
Cursor Shape
A container says which shape the pointer takes over it:
extern crate guido;
use guido::prelude::*;
fn main() {
let open = || {};
container()
.cursor(CursorIcon::Pointer)
.on_click(open)
;
}
After every pointer event the shape is resolved from where the pointer is: the
innermost widget under it that declares one wins, and with none the pointer is
the arrow. A text input declares the I-beam the same way, so a field inside a
clickable row shows Text over itself and Pointer over the rest of the row,
with nothing to reset when the pointer moves between them:
extern crate guido;
use guido::prelude::*;
fn main() {
let open = || {};
let query = create_signal(String::new());
container()
.cursor(CursorIcon::Pointer)
.on_click(open)
.child(text_input(query))
;
}
Like any other property it takes a signal, and a change reaches the screen
without the pointer having to move. A shape that is about a whole surface —
busy while something loads — is a cursor on its root:
extern crate guido;
use guido::prelude::*;
fn main() {
let loading = create_signal(false);
container().cursor(move || {
if loading.get() { CursorIcon::Wait } else { CursorIcon::Default }
})
;
}
CursorIcon::Hidden is a shape like the others: the pointer is still there and
still reaches widgets, but nothing is drawn for it. A surface with no pointer —
a lock screen, a kiosk — is Hidden on its root, and a widget inside can still
claim a visible shape, because the innermost claim wins:
extern crate guido;
use guido::prelude::*;
fn main() {
let unlock = || {};
container()
.cursor(CursorIcon::Hidden)
.child(container().cursor(CursorIcon::Pointer).on_click(unlock))
;
}
A text input’s I-beam is the innermost claim over it, so it shows even there; a
field that should not show it says so with its own cursor — see
Pointer Shape.
A container declared with takes_input(false) claims no cursor: the
compositor is not giving it the pointer, so whatever is beneath it answers.
Combining Events
A container can have multiple event handlers:
extern crate guido;
use guido::prelude::*;
fn main() {
let count = create_signal(0);
let hovered = create_signal(false);
container()
.on_click(move || count.update(|c| *c += 1))
.on_hover(move |h| hovered.set(h))
.when_hovered(|s| s.lighter(0.1))
.when_pressed(|s| s.ripple())
;
}
Event Propagation
Events flow through the widget tree from children to parents. A child receives events first; if it handles the event, the parent won’t receive it.
extern crate guido;
use guido::prelude::*;
fn main() {
// Inner container handles clicks, outer doesn't receive them
container()
.on_click(|| println!("Outer - won't fire for inner clicks"))
.child(
container()
.on_click(|| println!("Inner - handles click"))
.child(text("Click me"))
)
;
}
Hit Testing
Events only fire when the click is within the container’s bounds. Guido properly handles:
- Corner radius - Clicks outside rounded corners don’t register
- Transforms - Rotated/scaled containers have correct hit areas
- Nested transforms - Parent transforms are accounted for
Complete Example
extern crate guido;
use guido::prelude::*;
fn interactive_counter() -> impl Widget {
let count = create_signal(0);
let scroll_offset = create_signal(0.0f32);
container()
.layout(Flex::column().spacing(12.0))
.padding(16.0)
.children([
// Click counter
container()
.padding(12.0)
.background(Color::rgb(0.3, 0.5, 0.8))
.corners(8.0)
.when_hovered(|s| s.lighter(0.1))
.when_pressed(|s| s.ripple())
.on_click(move || count.update(|c| *c += 1))
.child(
container().child(text(move || format!("Clicked {} times", count.get())).color(Color::WHITE))
),
// Scroll display
container()
.padding(12.0)
.background(Color::rgb(0.2, 0.3, 0.2))
.corners(8.0)
.when_hovered(|s| s.lighter(0.05))
.on_scroll(move |_dx, dy, _source| {
scroll_offset.update(|o| *o += dy);
})
.child(
container().child(text(move || format!("Scroll offset: {:.0}", scroll_offset.get())).color(Color::WHITE))
),
])
}
fn main() {}
API Reference
// not compiled: a signature listing — these declarations have no bodies.
impl Container {
/// Handle click events
pub fn on_click(self, handler: impl Fn() + 'static) -> Self;
/// Handle the second click of a double click, on its release
pub fn on_double_click(self, handler: impl Fn() + 'static) -> Self;
/// Handle hover state changes
pub fn on_hover(self, handler: impl Fn(bool) + 'static) -> Self;
/// Handle a key press, or its release; each answers whether it took it
pub fn on_key_down(
self,
handler: impl Fn(Key, Modifiers, bool) -> EventResponse + 'static
) -> Self;
pub fn on_key_up(
self,
handler: impl Fn(Key, Modifiers) -> EventResponse + 'static
) -> Self;
/// The same, heard before the focused widget inside
pub fn on_key_down_capture(
self,
handler: impl Fn(Key, Modifiers, bool) -> EventResponse + 'static
) -> Self;
pub fn on_key_up_capture(
self,
handler: impl Fn(Key, Modifiers) -> EventResponse + 'static
) -> Self;
/// Make Tab stop here, and a press inside take the focus
pub fn focusable(self, focusable: bool) -> Self;
/// Handle scroll events
pub fn on_scroll(
self,
handler: impl Fn(f32, f32, ScrollSource) + 'static
) -> Self;
/// The pointer's shape over this container
pub fn cursor<M>(self, cursor: impl IntoSignal<CursorIcon, M>) -> Self;
}