Styling And Events
Styling And Events
Section titled “Styling And Events”Most visual and input behavior is expressed as chainable modifiers on typed components.
Use Theme roles for shared app semantics such as palette colors, text variants, radii, spacing, border sizes, shadows, and compound form controls. Use concrete values for isolated one-off visuals.
Visual Modifiers
Section titled “Visual Modifiers”use lurq::{components::Rect, node::color::Color};
Rect::new(120.0, 40.0) .background("#2563eb") .rounded(8.0) .border_inside(1.0, Color::from_hex("#1d4ed8"))Common visual modifiers:
| Modifier | Purpose |
|---|---|
.background(color) | Background color from a concrete color or PaletteColor. |
.background_gradient(gradient) | Linear, radial, or conic gradient fill. See Gradients. |
.foreground(color) | Color of the text in the element and under it. See Foreground. |
.rounded(radius) | Uniform corner radius from f32 or RadiusSize. |
.corner_radius_* | Per-corner radius from f32 or RadiusSize. |
.border_inside(width, color) | Border inside the element bounds from a concrete width or BorderSize. |
.border_center(width, color) | Border centered on the element edge from a concrete width or BorderSize. |
.border_outside(width, color) | Border outside the element bounds from a concrete width or BorderSize. |
.border(border), .border_top(border) … | A Border on every side or on one, solid or dashed. See Borders. |
.box_shadow(shadow) | Drop or inset shadows from a ShadowStyle role, a BoxShadow, or a list. See Box Shadows. |
.outline(outline) | A line around the element, outside its box, that takes no room in layout. See Outline. |
.opacity(value) | Fade the element and its subtree as one group. See Opacity. |
.blur(radius) | Blur the element and its subtree as one layer. See Blur. |
.backdrop_blur(radius) | Blur what is painted behind the element: frosted glass. See Blur. |
.clip() | Clip descendants to this element. |
.overflow_visible() | Allow descendants to paint outside this element. |
An element clips its descendants by default; one with corner radii clips them to its rounded box, inside its border,
and a press past a rounded corner does not reach what the corner cuts off. Clips nest as overflow: hidden with
border-radius does in CSS: content is cut by every clip it is under, so a rail along the bottom of a rounded panel, a
picture across its top or a scrolling list down to its bottom corners keeps the panel’s round corners even though it
clips itself, and a child with corners of its own at the panel’s corner is cut by both. Two rounded clips that cut the
same content are followed exactly; where three would, the outermost is left out.
Translucent colors ("#000000a6", .opacity(...), anti-aliased edges, text, images) blend on the sRGB-encoded
channels, as CSS and design tools do: a #000000a6 scrim over #eeeeee shows #535353. Both native backends render
through a non-sRGB target to get this; the devtools screenshot renderer blends the same way.
Colors
Section titled “Colors”node::color::Color is a color of 8-bit red, green, blue and alpha. Color::from_hex("#2563eb") and "#2563eb".into()
read a color the app writes in its code and panic on one that is no color; Color::parse(text) reads what a person
typed and gives None for what is no color:
use lurq::node::color::{Color, Hsv};
let blue = Color::parse("rgb(37 99 235)").unwrap();assert_eq!(Color::parse(" #2563eb "), Some(blue));assert_eq!(Color::parse("hsl(221deg 83% 53% / 50%)").map(|c| c.a()), Some(128));assert_eq!(Color::parse("blue"), None);
assert_eq!(blue.to_hex_upper(), "#2563EB");assert_eq!(blue.with_alpha(128).to_rgb_string(), "rgba(37, 99, 235, 0.5)");// By hue, saturation and value, and back: what a color picker moves.let hsv: Hsv = blue.to_hsv();assert_eq!(Color::from(hsv), blue);| Read and written | |
|---|---|
Color::parse(&str) | #rgb, #rgba, #rrggbb, #rrggbbaa (with or without #), rgb(..)/rgba(..) of numbers from 0 to 255 or percents, hsl(..)/hsla(..) with the hue in degrees, by commas or by spaces with the alpha after /, the alpha from 0 to 1 or a percent; case and space around are not read |
to_hex(), to_hex_upper() | #2563eb, #2563EB; with the alpha (#2563EB80) where it is not opaque |
to_rgb_string(), to_hsl() | rgb(37, 99, 235), rgba(37, 99, 235, 0.5); hsl(..), hsla(..) |
to_hsv(), Color::from(Hsv) | Hue in degrees from 0 to 360, saturation, value and alpha from 0 to 1. A grey has no hue: it is 0 |
to_hsl_values(), Color::from(Hsl) | Hue, saturation, lightness and alpha, as CSS’s hsl() has them |
A plane of colors, as a picker’s area of saturation and brightness, is one box filled with Gradient::corners(white, hue, black, black): see Four corners.
Foreground
Section titled “Foreground”.foreground(color) sets the color of the text in an element and under it, as CSS color does. A Text that names no
color of its own is drawn in the foreground of its nearest ancestor that has one:
use lurq::{ app::theme::PaletteColor, components::{Row, Text},};
// Both labels are white; the count is the muted role.Row::new() .background("#171717") .foreground("#fafafa") .child(Text::new("Inbox")) .child(Text::new("Unread")) .child(Text::new("12").color(PaletteColor::MutedForeground))- The color is a concrete color or a
PaletteColor, which follows the theme. - A text’s own color wins:
Text::color(...), and the color of the style given toText::styled(...). A style that keeps the default text color names none: its text takes the foreground like a text with no style. - A text with a typography variant and no color of its own takes the foreground in place of the variant’s color.
- With no foreground above it a text keeps its typography style’s color, and where that is the default text color, the theme’s foreground: see The theme’s foreground.
- A fill can be the foreground too:
.background(BackgroundColor::CurrentForeground)paints an element in the color a text there would have, its own foreground, the nearest one above it, or the theme’s. A mark that is a fill, a dot or a bar, goes with the text around it so. It runs no transition of the background. .foreground(...)on aTextsets the color of that text.- A
TextInputand Markdown draw in their own styles and do not read it. - The content of an overlay (a popup, a modal, a select’s menu) is painted outside the element that declares it and starts from no foreground. Set one on the overlay’s content.
- It is paint only: it changes no size or position. On a live element use
ElementHandle::set_foreground.
The theme’s foreground
Section titled “The theme’s foreground”PaletteColor::Foreground is the color of text that names none: the design’s near-black in the light palette and
its near-white in the dark one. In the legacy theme it is black, the color of
TextStyle::default(), which text had before the role.
// Light text for a dark theme: every text that names no color follows.app.theme().set_palette_color(PaletteColor::Foreground, Color::from_hex("#fafafa"));A style that keeps the default text color names no color, and the theme’s foreground stands in for it:
- a
Textwith no color, whether it has no variant, a typography variant whose style keeps the default color, or a style given toText::styled(...)that keeps it; - a
TextInput’s text, its placeholder where that has no style of its own, and its caret; - a Markdown document whose style keeps the default color.
A typography style with a color of its own keeps it, and so does a text with Text::color(...). A .foreground(...)
above a text comes first, as described above. To draw text in exactly the default black under another foreground, name
it: Text::color("#000000").
Borders
Section titled “Borders”.border_inside, .border_center and .border_outside draw a line of one width on all four sides, inside the
element’s box, centered on its edge, or outside it. .border(border) takes a Border, and .border_top,
.border_right, .border_bottom and .border_left set one side each:
use lurq::{components::Row, node::border::Border};
// A card with an accent on its left edge and a dashed drop target.Row::new().rounded(8.0).border_left(Border::inside(3.0, "#2563eb"));Row::new().rounded(8.0).border(Border::inside(1.0, "#94a3b8").dashed());- A border follows the element’s corner radii. The corner of its inner edge is the corner’s radius less the widths of the two sides that meet there, as CSS shapes a padding box, so sides of different widths meet in a smooth curve.
- A border on some sides of a rounded element goes on round a corner whose other side has none at its full width, its inner edge concentric with the outer one, and fades out along the arc: opaque where the arc leaves the bordered side, gone where it reaches the side with none. It does not thin out as in CSS, so a line under a tab or along the bottom of a panel follows the shape and dissolves at its ends. Between two square corners it is a plain band that ends at the element’s edge.
- A border outside or centered on a rounded element keeps the element’s corners for its inner edge and is rounder on its outer edge by its width. A square corner stays square. Round a corner whose other side has none it reaches past that side as far as past its own; it paints there only, and layout and hit testing do not change.
- Sides with the same placement and dash are painted as one shape, whatever their widths and colors. Where two of them meet at a rounded corner and differ in color, the color goes over from one to the other along the arc with nothing lighter in between; at a square corner they meet on the diagonal. Sides of different placements or dashes are painted apart, each as a border of its own.
Dashed borders
Section titled “Dashed borders”Border::dashed() cuts the line into dashes three times its width long, with gaps as long.
Border::dash(dash, gap) sets both lengths, in logical pixels:
Border::inside(2.0, "#64748b").dashed(); // 6 on, 6 offBorder::inside(1.0, "#64748b").dash(4.0, 2.0);The dashes run along the element’s outline, around its corners, clockwise from the start of its top edge. The period is fitted to the outline’s length, so the last dash meets the first with a whole gap between them and the lengths drawn can differ a little from the ones given. A dashed border on some sides only shows the dashes that fall on them; the dashes of a single side run to its ends. A border with no dash or no gap is a solid line.
Opacity
Section titled “Opacity”.opacity(value) fades an element together with everything inside it, as CSS opacity, Figma and Pencil do: the
subtree is painted into an offscreen layer as if it were opaque, and the layer is then blended over what is behind it
once, at value. Content inside the group blends only with other content of the group. A dark label on a light fill
at opacity(0.4) keeps its contrast against the faded fill, and a border drawn over the fill’s edge adds no lighter
ring:
use lurq::components::{Stack, Text};
// Disabled primary button over a #1c1c1c window: the fill shows #6c6c6c and the// label #1a1a1a, the colours a design tool shows for the same group.Stack::new() .size(100.0, 36.0) .background("#e4e4e4") .border_inside(1.0, "#e4e4e4") .rounded(6.0) .opacity(0.4) .child(Text::new("Save").color("#171717"))- Nested opacities compose: a group at
0.5inside a group at0.5shows its content at0.25where it covers nothing else of the outer group. - A group that paints a single primitive (a fill without a border, one text run without a shadow, an image, a
rasterized SVG, a box shadow) looks the same either way, so it fades that primitive directly and needs no layer.
Opacity
1(the default) never makes a layer. - A layer covers the group’s painted pixels in whole physical pixels, within its clips and the window, and maps one to
one onto the window’s pixels: it is never resampled, so it stays sharp at fractional scale factors such as 1.25 and
1.5. Layer textures are pooled and reused across frames; a group that is clipped away or at
opacity(0.0)paints nothing. - Opacity changes painting only. Layout, clipping, scrolling, transforms and hit testing are the same at any opacity: a faded element still takes clicks unless it is disabled some other way.
RenderList::layerslists the layers of a frame (LayerCmd: the render orders a layer groups, its opacity and pixel bounds). A customRenderEnginecomposites each layer’s draws into its own target, or draws them without a layer and loses the flattening.
.blur(radius) blurs an element together with everything inside it, as CSS filter: blur() does, and
.backdrop_blur(radius) blurs what is painted behind an element, inside its box, as CSS backdrop-filter: blur()
does: frosted glass for an element with a translucent background.
use lurq::components::{Column, Text};
// A glass toolbar over whatever scrolls under it.Column::new() .padding(12.0) .background("#ffffff40") .rounded(12.0) .backdrop_blur(16.0) .child(Text::new("Toolbar"))The radius is in logical pixels, with the Gaussian’s deviation at half of it, as for a shadow’s blur radius; 0 (the
default) is no blur. Both change painting only, follow the element’s transforms and the clips it is under, and
animate with Transition::blur() and Transition::backdrop_blur(). Blur has the rules for edges,
clips, layers and cost.
Gradients
Section titled “Gradients”.background_gradient(...) fills an element with a CSS-like gradient. It is separate from .background(color); if both are set, the gradient paints the fill. Gradients respect the element’s rounded corners, clipping, and .opacity(...) just like a solid background.
use lurq::{components::Rect, node::{Gradient, GradientStop}};
Rect::new(240.0, 120.0) .rounded(12.0) .background_gradient(Gradient::linear(135.0, ["#ff0080", "#7928ca"]))Four kinds are supported on both the wgpu and dx12 backends:
| Constructor | Description |
|---|---|
Gradient::linear(angle_deg, stops) | Linear gradient. angle_deg follows CSS: 0 points up, increasing clockwise (90 is to the right). The line is sized so 0%/100% reach the box corners. |
Gradient::radial(stops) | Radial gradient, farthest-corner. Defaults to an ellipse fitted to the box; call .circle() for a circle. |
Gradient::conic(from_deg, stops) | Conic gradient sweeping clockwise from from_deg at the top. |
Gradient::corners(top_left, top_right, bottom_right, bottom_left) | The blend of four colors, one at each corner of the box: a point is the mix of the top two across and of the bottom two, mixed down (bilinear), in the colors’ sRGB values, as a picture is written. See Four corners. |
Color Stops
Section titled “Color Stops”Stops accept anything that converts into a color (hex strings, Color, or a PaletteColor), so theme palette colors work inside gradients. A bare color is auto-positioned; use GradientStop::at(color, position) for an explicit position in 0.0..=1.0.
use lurq::node::{Gradient, GradientStop};
// Auto-spaced: first at 0.0, last at 1.0, middle evenly distributed.Gradient::linear(90.0, ["#f00", "#0f0", "#00f"]);
// Explicit positions and a palette color (lurq::app::theme::PaletteColor).Gradient::linear(90.0, [ GradientStop::at("#000", 0.0), GradientStop::at(PaletteColor::Primary, 0.4), GradientStop::at("#fff", 1.0),]);Omitted positions follow the CSS rules: the first defaults to 0.0, the last to 1.0, and runs of omitted stops are spread evenly between their defined neighbors. Colors are interpolated in linear space (CSS interpolates in sRGB, so midpoints are lighter than a browser’s); the result then blends over what is below like any other translucent color.
Center And Shape
Section titled “Center And Shape”use lurq::node::Gradient;
// Radial circle centered in the top-left quadrant.Gradient::radial(["#fff", "#1e293b"]).circle().center(0.25, 0.25);
// Conic starting from 45 degrees, centered.Gradient::conic(45.0, ["#f43f5e", "#8b5cf6", "#06b6d4", "#f43f5e"]);.center(x, y) moves the radial/conic origin; coordinates are normalized 0.0..=1.0 within the element (default (0.5, 0.5)).
Four Corners
Section titled “Four Corners”Gradient::corners fills a box with the blend of the colors at its corners: the area of a color picker is white, the hue, black and black, so a point of it at saturation s and brightness v is v · mix(white, hue, s).
use lurq::{components::Row, node::{Gradient, color::Color}};
let hue = Color::from_hex("#2563EB");Row::new() .size(208.0, 120.0) .rounded(6.0) .background_gradient(Gradient::corners("#fff", hue, "#000", "#000"));Draw a picture of several fills as one box, with one such fill, rather than boxes stacked under one rounded clip. Each stacked box is cut by the clip on its own, with an edge of its own: where the edge covers a pixel by half, the top box lets half of what is under it through, and that one half of what is under it in turn, so the lowest box shows at the rounded edge (a rim of the hue around the black corners of a picker’s area, before it was one box). A translucent fill over an opaque one (a rail of alpha over its checkerboard) lets the lower one through at the edge by a · c · (1 − c) of the difference between it and what is behind, where c is the edge’s cover and a the upper fill’s alpha: a rim of the lower one’s color, which shows only where that color differs from the panel’s.
Box Shadows
Section titled “Box Shadows”.box_shadow(...) gives an element CSS-like box-shadows. It takes a ShadowStyle theme role, which is what app UI should use, or concrete BoxShadow values for one-off visuals:
use lurq::{ app::theme::ShadowStyle, components::Rect, node::BoxShadow,};
// A theme elevation.Rect::new(240.0, 120.0).background("#ffffff").rounded(12.0).box_shadow(ShadowStyle::Md);
// offset_x, offset_y, blur, color; spread and inset are optional.Rect::new(240.0, 120.0) .background("#ffffff") .rounded(12.0) .box_shadow([ BoxShadow::new(0.0, 1.0, 2.0, "#0f172a1f"), BoxShadow::new(0.0, 12.0, 32.0, "#0f172a40").spread(-4.0), ]);
// An inset well.Rect::new(240.0, 40.0) .background("#ffffff") .box_shadow(BoxShadow::new(0.0, 2.0, 6.0, "#0000004d").inset());A BoxShadow follows CSS and design tools such as Figma and Pencil:
| Field | Meaning |
|---|---|
offset_x, offset_y | Moves the shadow, in logical pixels. |
blur | CSS blur radius: a Gaussian with a standard deviation of blur / 2. 0 is a hard edge. |
spread | Grows the shadow shape (negative shrinks it) before the blur. Corner radii grow and shrink with it as CSS specifies, so square corners stay square. |
color | A Color, hex string, or PaletteColor role. |
inset | Paints inside the element instead of beneath it (.inset()). |
How shadows paint:
- A list paints first on top. Outer shadows paint beneath the element’s background; inset shadows above the background and below the border and the children, inside the padding box (within an inside or centered border).
- An outer shadow follows the element’s corner radii and paints only outside its box, so it never shows through a translucent background.
- Shadows never change layout and are not hit-tested: a click on a shadow goes to whatever is under it.
- Shadows take the element’s
.opacity(...)and transform, and its clip: an ancestor that clips its children clips their shadows too. Containers clip by default, so give a shadow room with padding, or call.overflow_visible()on the containers it should escape (as with any child that paints outside its parent). - Values scale with the display like every other length.
- Hover, active, and focus styles can change the shadow, for example to raise a card on hover with
.hovered(|style| style.box_shadow(ShadowStyle::Lg));BoxShadowValue::none()removes it.
Both native backends evaluate the blurred rounded rect analytically in the quad shader (a closed-form erf along one axis, eight samples along the other), so a shadow is one more instance in the quad pipeline: no offscreen pass and no blur texture. wgpu and DX12 render the same pixels; the devtools screenshot renderer uses the same formula on the CPU.
Outline
Section titled “Outline”.outline(Outline::new(width, color)) draws a line around an element, outside its box, as CSS outline does, and
.offset(px) on the outline leaves a gap between the box and the line, as outline-offset does. It is what a focus
ring is made of:
use lurq::{ app::theme::PaletteColor, components::Button, node::Outline,};
Button::new("Save") .rounded(6.0) .focus_visible(|style| style.outline(Outline::new(2.0, PaletteColor::Ring).offset(2.0)))- The width is logical pixels or a
BorderSizerole; the color is a concrete color or aPaletteColor. - It takes no room in layout: showing or hiding it moves nothing, unlike a border, which is part of the box.
- The line follows the element’s corner radii, grown by the offset and the width, so the ring stays concentric with a rounded control. A square corner stays square.
- A negative offset draws the line inside the box.
- It is painted over the element’s own content and over the elements painted after it, as CSS paints an outline: of two buttons side by side with no gap, the ring of the first lies over the second. It stays with what its element is painted with: under the border and the bars of the scroll container it scrolls in, under an element that sticks over it, inside the layer of an ancestor with an opacity or a blur, and under a menu or a dialog over the page.
- A container clips its content to its bounds, but not the ring of what touches its edge: an outline reaches past the containers its element is in by its own offset and width, so a button that fills its row keeps its whole ring with no padding around it. An element that is itself cut by a container is cut with its ring.
- A scroll container and the window cut the ring where they cut the element: what scrolls out of view takes its ring with it.
- An outline with no width, or
Outline::none(), paints nothing; a state style usesOutline::none()to remove the element’s own outline. - On a live element use
ElementHandle::set_outline.
Hover, Active, And Focus Styles
Section titled “Hover, Active, And Focus Styles”State styles merge into the base style while the node is hovered, active, focused, or focus-visible.
use lurq::{components::Text, node::CursorIcon};
Text::new("Save") .padding_horizontal(12.0) .padding_vertical(8.0) .background("#2563eb") .rounded(6.0) .cursor(CursorIcon::Pointer) .hovered(|style| style.background("#3b82f6")) .active(|style| style.background("#1d4ed8")) .focus_visible(|style| style.border_inside(1.0, "#93c5fd".into()))CursorIcon::None draws no pointer while it is over the element, as a video player hides it while its controls have faded; any other cursor shows it again.
The focused style (.focused(...)) shows whenever the node has focus, whether a click, Tab, or a focus request put it there. The focus-visible style (.focus_visible(...)) shows only for keyboard focus, like CSS :focus-visible: Tab or a key press shows it, a click does not, and a text input shows it for any focus. Use it for focus rings. Checkboxes, sliders and selects also have part-level focus styles, which follow focus-visible; see Focus-Visible and Focused Styles.
A fifth state style, .drag_over(...) (drag_over_style), applies while files from the OS are dragged over the node; see File Drag And Drop.
A state style can also set:
.foreground(color): the color of the text in the element and under it while the state holds (see Foreground), so one style recolors a button’s label and icon together..opacity(value): the opacity of the element and its subtree while the state holds, in place of the element’s own. ATransition::opacity()on the element animates the change..outline(outline): an outline while the state holds, typically a focus ring infocus_visible.
These three change painting only. Where several state styles set the same value, the one applied last wins: the disabled style, then drag-over, active, hovered, focus-visible, focused, and last the style within an interaction group.
use lurq::{components::{Row, Text}, node::Outline};
// A ghost button: one hover style changes the fill and the label.Row::new() .padding_horizontal(12.0) .padding_vertical(8.0) .rounded(6.0) .foreground("#18181b") .hovered(|style| style.background("#d9d9e0").foreground("#09090b")) .active(|style| style.opacity(0.8)) .focus_visible(|style| style.outline(Outline::new(2.0, "#71717a").offset(2.0))) .child(Text::new("Cancel"))State styles can affect layout if they change frame, padding, or flex. That is supported, but it can force relayout when interaction state changes.
Use ctx.interaction() when component code needs to read the current interaction state:
let interaction = ctx.interaction();let hovered = interaction.is_hovered();Attach the state to an element with .interactive(interaction) if you need to observe that element’s state from component code.
Within An Interaction Group
Section titled “Within An Interaction Group”.interaction_group(true) makes an element a group: while the pointer is on it, or the focus is on it or in it, the
elements in it show their .within_style(style). An action at the end of a row that shows only while the row is
pointed at or focused is a style within the row’s group.
use lurq::{ components::{Button, Row, Text}, node::Style,};
// The delete button shows while the pointer is on the row or the focus is in it.Row::new() .padding_horizontal(12.0) .interaction_group(true) .hovered(|style| style.background("#f4f4f5")) .child(Text::new("report.pdf")) .child( Button::new("Delete") .tab_index(0) .opacity(0.0) .within_style(Style::new().opacity(1.0)), )- The pointer anywhere on the group lights it, on an element in it as well as between them. The focus on the group or on anything in it lights it too, so a keyboard reaches the action and sees it.
- An element in two groups answers to the innermost: a group inside another lights only what is in it, and the outer one lights the rest.
- An element in no group answers to the innermost button it is in, as to a group: the label of a button styled by
the button’s hover (
Recipe::within_hovered(ButtonPart::Label, ..)) is painted while the button is under the pointer. A button in a group is no group of its own; a button in a button that is one lights only what is in it. - It paints only, as the disabled style does: a frame, padding or flex in it is ignored, so nothing moves as it comes and goes. It is laid under every other state style.
- An element hidden by it (opacity 0) is still under the pointer and still a stop of Tab; with the pointer on it, its
group is lit and it shows. A design system’s recipe names it
within(see Recipes).
.within_hovered_style(style) is laid over the within style while the group is under the pointer, and not while it only
holds the focus; .within_pressed_style(style) over that while the group is held down. A cell of a table that stays
while the row scrolls sideways covers the row’s veil with its fill, so it takes the veil itself, by its row’s hover and
press: the row clicked keeps the focus, and the cell is not veiled once the pointer leaves it.
use lurq::{ components::{Row, Text}, layout::layout_kind::Sticky, node::Style,};
Row::new() .interaction_group(true) .hovered(|style| style.background("#f4f4f5")) .active(|style| style.background("#e4e4e7")) .child( Row::new() .sticky(Sticky::left(0.0)) .background("#ffffff") .within_hovered_style(Style::new().background("#f4f4f5")) .within_pressed_style(Style::new().background("#e4e4e7")) .child(Text::new("report.pdf")), )A recipe says them as within with hovered or pressed (Recipe::within_hovered, Recipe::within_pressed, or
Selector::new().within().hovered()).
Disabled
Section titled “Disabled”.disabled(true) takes an element and everything in it out of input:
use lurq::components::{Button, Row};
// Neither button can be clicked, focused or reached with Tab.Row::new() .disabled(saving) .when_disabled(|style| style.opacity(0.5)) .child(Button::new("Save").on_click(save)) .child(Button::new("Discard").on_click(discard))- No press, click, double click, tap, long press or drop reaches a disabled element or anything in it, and none of them is hovered, pressed or focused. Built-in controls in it (text inputs, checkboxes, sliders, selects, links) do nothing.
- Tab passes it by,
ctx.focus(...)andElementHandle::focus()on it are ignored,ElementHandle::click()does nothing, and an element that had focus when it, or an element it is in, became disabled loses it. - It still covers what is behind it: a press on a disabled element reaches nothing. That includes the elements it is in, as with a disabled control on the web: a clickable card is not clicked through its disabled button. A press on it leaves focus where it is.
- A pointer that moves over it still reaches the elements it is in: a row stays hovered over its disabled button.
- It still hears the pointer come and go: its
on_mouse_enterandon_mouse_leaverun as the pointer comes onto it and leaves it, so a tooltip can say why it is disabled. Nothing else of the pointer reaches it: it is not hovered and its hovered style is not drawn. - Scrolling is not input to a control, so it works as if nothing were disabled: a wheel or a finger over a disabled
element scrolls the containers the element is in and the scroll containers inside it, and their scrollbars can be
dragged, so what a disabled panel holds can be read to its end. Scroll handlers (
on_scroll) of the disabled element and of what is in it do not run, other than those of its scroll containers. - The disabled style,
.when_disabled(|style| ...)or.disabled_style(style), is merged over the element’s style after every other state style while the element is disabled, by itself or by an element it is in, so each element in a disabled group can have its own. It changes painting only: a frame, padding or flex in it is ignored. Use.opacity(...)or.foreground(...)in it to dim a whole control from its root, and.cursor(...)for the cursor over it. InteractionState::is_disabled(), on a state given to an element with.interactive(state), istruefor a disabled element and for the elements in it, in view or not. It is written when the tree is built and when a live element is disabled or enabled, so it is right as soon as either has happened.- On a live element use
ElementHandle::set_disabled.
Disabling is about input. It sets no look of its own: without a disabled style a disabled element is painted as before.
Mouse Events
Section titled “Mouse Events”use lurq::app::events::MouseEvent;
Rect::new(100.0, 40.0) .on_mouse_down(|event: MouseEvent| println!("down {:?}", event.button)) .on_mouse_up(|event: MouseEvent| println!("up at {}, {}", event.x, event.y)) .on_click(|event: MouseEvent| println!("click target {:?}", event.target_id)) .on_dblclick(|event: MouseEvent| println!("double click {:?}", event.target_id)) .on_mouse_move(|event: MouseEvent| println!("move {}, {}", event.x, event.y)) .on_mouse_enter(|| println!("enter")) .on_mouse_leave(|| println!("leave"))Hover follows the content under a pointer that holds still: after a layout that moved anything (a wheel scroll, a list that grew, a stick-to-bottom chat taking a new message), lurq hit-tests the hover again at the pointer’s last position, as a browser does. The node that moved away gets on_mouse_leave and loses its hovered style, the node now under the pointer gets on_mouse_enter, and the frame that shows the new layout already shows the result, so a hover tooltip never stays behind its row. Nothing is hovered again while the pointer is outside the window or a drag holds it. The handlers run with the source of the input that last moved the pointer (see Synthetic Input), so an agent’s pointer stays synthetic. A hover style that moves its own node off a still pointer (a hovered size, offset or transform) unhovers it, which moves it back, which hovers it again: like CSS :hover, such a node flickers, so keep hover styles from moving the node away from the pointer.
An element is under the pointer on the device pixels it covers: from its left and top edges up to, and not on, its right and bottom ones. The row of pixels under a row is the next row’s, or the gap’s between them, and of two rows that touch each has the pointer on its own pixels. HitRect::contains tells the same of a point.
A box is drawn where it is laid out, at a fraction of a device pixel where the scale is no whole number (150%), and its edge there is a column of half covered pixels. .snap_to_pixels(true) draws the fills and borders of an element and of everything in it on whole device pixels: each edge goes to the device pixel nearest it when the frame is painted, and an edge half way between two goes to the lower one whichever box it is the edge of, so two boxes that meet still meet. It is for a grid of cells that must read sharp, as the modules of ui::QrCode. What is laid out and what the pointer hits are as before; a text, an image and a box that is turned are drawn where they are.
The hover moves whenever the pointer comes onto another node, from a row onto the text inside it for one, and most nodes look the same under the pointer. Every such move updates the hover and the cursor and runs the handlers, but it asks for a frame only when it shows, that is, when a node that gained or lost the hover:
- has a
hoveredstyle, whose paint, layout and transitions the frame draws, or any state style that changes frame, padding or flex, which lays the node out again when one of its states changes; - is a checkbox, a slider, a select or a Markdown link, which paint a hover look of their own;
- scrolls (a scroll container, a
VirtualizedList, a multilineTextInput): its scrollbar may show for the pointer and loses its hovered style with it; - ran an
on_mouse_enteroron_mouse_leavehandler, whatever the handler did.
While DevTools is open on the window, every change of the hover is drawn, since DevTools shows which elements are hovered. Otherwise the pointer moving over elements with none of the above draws nothing, however many of them it crosses. ElementRef::hovered() and InteractionState::is_hovered() are plain reads, not signals: they are up to date after every pointer move, but a change of them renders no component and asks for no frame. A component that renders again when the pointer comes onto an element sets a signal from on_mouse_enter and on_mouse_leave.
MouseEvent includes x, y, button, kind, target_id, pointer_kind (what pressed: PointerKind::Mouse, Touch or Pen, as a browser’s pointerType; a key’s click and input synthesized as the mouse’s are Mouse), the modifiers shift, ctrl, alt and meta (Cmd on macOS, the Windows key on Windows), and from_keyboard: a click that Enter on a focused link, or Enter or Space on a focused button, made, with the key’s modifiers, button Left and x, y at 0. A shell that drives a Tree itself passes Meta with Tree::mouse_move_with_meta, mouse_down_with_meta and mouse_up_with_meta. See Event Control for prevent_default() and propagation methods.
Each on_* modifier appends a handler for that rendered node, so a node can have multiple handlers for the same event. Inline closures are render output: when the node is rendered again, the rendered handler list should replace the previous list.
Use a stable EventHandler when you need to remove the exact handler later:
use lurq::{app::events::MouseEvent, node::EventHandler};
let handler = EventHandler::new(|event: &MouseEvent| { println!("click target {:?}", event.target_id);});
let node = Rect::new(100.0, 40.0) .on_click(handler.clone()) .off_click(handler);Use ctx.on_click_outside with an element ref when a component needs to react to clicks outside one of its own nodes:
let menu_ref = ctx.element_ref();let open = self.open.clone();ctx.on_click_outside(menu_ref.clone(), move |_| open.set(false));
Column::new() .ref_element(menu_ref) .child(Text::new("Menu"))The hook listens for left clicks outside the referenced element’s measured bounds. It is removed automatically when the component stops calling it during render.
A Click Is The Action, A Tap Is The Gesture
Section titled “A Click Is The Action, A Tap Is The Gesture”on_click is “activate”, from any input: a mouse, a finger, a pen, Enter or Space on a focused control, and input a
tool synthesizes. An app writes its actions there, once for a phone and a desktop. on_tap, on_double_tap,
on_swipe, on_pinch, on_long_press and the rest are gestures, from a finger or a pen only. A finger’s tap is
told as on_tap first and on_click after, each once; a tap a handler takes clicks nothing, a tap of two fingers
never clicks, and a click waits for a second tap only on an element with on_double_tap. See
Touch for the gestures.
Every Gesture
Section titled “Every Gesture”Every gesture reaches the app through one path, a finger’s (Tree::finger):
a touch screen’s on a phone, a tablet or a touch laptop, the mouse’s under the emulator,
and an agent’s through MCP’s lurq_touch. An app writes its handlers once and tries them
on a desktop.
| Gesture | What it means | Event | On a phone | In the emulator | Through MCP (lurq_touch) |
|---|---|---|---|---|---|
| Tap | Activate; a gesture of some fingers | on_tap (fingers, count), then on_click for one finger | Touch and lift | Click | tap (fingers, count) |
| Double tap | Zoom to a point; select a word in text | on_double_tap, on_tap with count 2 | Tap twice | Double click | double_tap, or tap with count 2 |
| Long press | A context menu; in text, the caret with the loupe | on_long_press | Hold still half a second | Hold the button still | long_press (duration_ms) |
| Pan | Drag what follows the fingers; scroll | on_pan, and the scroll with momentum | Drag | Drag | pan (dx, dy, or direction and distance) |
| Swipe | A flick: next, previous, dismiss | on_swipe (direction, fingers, velocity) | Flick and lift | Drag quickly and let go | swipe (direction, distance, speed, fingers) |
| Edge pan | Back (from the left) or forward (from the right) | on_edge_pan, then on_history_swipe, then going back | Drag in from an edge | Drag in from the window’s edge | edge_pan (edge, distance) |
| Pinch | Zoom | on_pinch (scale) | Two fingers apart or together | Alt+drag away from or toward where it began | pinch (scale) |
| Rotate | Turn | on_rotate (rotation) | Two fingers turning | Alt+drag around where it began | rotate (angle) |
| One-finger zoom | Zoom with one hand | on_pinch (down zooms in) | Tap, then land again, hold and drag | Click, then press again and drag | zoom (scale) |
| Two fingers | A pan or a swipe of two | on_pan, on_swipe with fingers 2 | Two fingers together | Alt+Shift+drag | pan, swipe with fingers 2 |
| Three-finger swipe | Undo (left), redo (right) | on_swipe with fingers 3, then EditCommand::Undo / Redo | Three fingers flicked sideways | Alt+Shift+Ctrl+drag sideways | three_finger_swipe (direction) |
| Three-finger pinch | Copy (in), paste (out) | EditCommand::Copy / Paste | Three fingers pinched | Alt+Shift+Ctrl and the wheel, no button: away spreads them, toward closes them; let go of the keys to lift | three_finger_pinch (scale) |
| Three-finger tap | The menu of editing commands | on_tap with fingers 3, then the menu | Three fingers tapped | Alt+Shift+Ctrl+click | tap with fingers 3 |
| Pull to refresh, swipe actions | A list’s | See iOS | Drag a list down; a row sideways | Drag | pan, swipe |
| Bounce | A list pulled or thrown past its end springs back | The list’s scroll | Drag or flick past an end | Drag or flick past an end | pan, swipe |
| Pen hover | A pen near the screen hovers | on_mouse_enter, on_mouse_move, hover styles; pointer_kind Pen | An Apple Pencil over an iPad; a pen over a Windows screen; a browser’s pen | The mouse hovers nothing | Not made |
Three fingers’ commands run as their keys would (Editing commands) on
what has the focus, where nothing took their swipe or tap (prevent_default). Their tap opens the menu of editing
commands: lurq shows it over the app by itself, a ContextMenu’s bar in the theme’s
context_menu recipe, its words the locale’s (locale.editing.undo, cut, copy, paste, redo,
locale.common.select_all), and choosing one leaves the focus where it was. Window::edit_menu() says whether it is
open and where; Window::set_edit_menu(None) closes it. On iOS, where the system’s text input has the focus, lurq
leaves three fingers to the system.
Text by touch. Where the platform draws no caret of its own (everywhere but iOS, which has its own), lurq draws a phone’s:
- a long press in a text input puts the caret under the finger with a loupe over it, a magnified view of the text around the caret; the caret goes with the finger until it lifts, and the menu opens over it with Select all and Paste;
- a selection in the focused input while the pointer is a finger has two handles, a knob on a stem at each end
in the theme’s
Primary; a finger that lands on one drags that end; - a selection a finger makes (a double tap selects a word, a triple tap a line), or a handle let go, opens the menu over the selection: Cut, Copy, Paste, Select all.
Under emulation nothing hovers (a finger cannot), the wheel still scrolls and the keyboard still types. A gesture of the mouse’s fingers starts where the button went down; while a modifier is held the fingers it would make are drawn as dots.
A Finger Or A Mouse
Section titled “A Finger Or A Mouse”lurq::app::Pointer says what the person points with: Fine (a mouse, a trackpad, a pen: a point a pixel wide,
which can hover) or Coarse (a finger: a point a fingertip wide, which cannot). It is a fact about the device in the
person’s hand, beside the theme and not in it: a theme’s density says how large rows are, the pointer says whether
a component is dressed for a finger (see the touch form).
- At the start it is the platform’s (
Pointer::platform_default()):Coarseon iOS and Android,Fineon Windows, macOS and Linux, and in the browser what the page’s(pointer: coarse)media query says of the device’s primary pointer. - Then it follows the last input: a finger that touches the window makes it
Coarse, a mouse or a trackpad that moves makes itFine, and a pen leaves it as it is. Only the first input of the other kind changes it; a move of the kind it is at costs nothing. A laptop with a touch screen isCoarseafter a finger andFineafter the trackpad; an iPad with a trackpad the same. - Where touches come from. The shell gives a finger to the tree as a touch on every platform winit tells touches
on: iOS, Android, Windows (a touch screen), Linux (X11 and Wayland) and the browser (pointer events whose
pointerTypeistouch); macOS has no touch screen. Windows also makes mouse messages of every touch; the shell drops them (they carry the system’s mark,MI_WP_SIGNATURE), so a tap is one click and not two. A pen is told where the platform tells it: an Apple Pencil on iOS (it has an angle), a pen on Windows (it comes as pointer input with its pressure, a finger asWM_TOUCHwith none), and a pen in the browser, which winit gives as the mouse and the shell knows by the event’spointerType. On Android and Linux winit does not say a touch is a pen’s: it is a finger’s there. A pen in the browser clicks and isPointerKind::Pen, but has noon_tap, since it reaches lurq as the mouse. - The app pins it with
App::set_pointer(Pointer::Coarse): a kiosk with a touch screen, a preview of the phone’s forms on a desktop. Input then does not move it.App::follow_pointer(false)keeps it where it is without pinning a value, andfollow_pointer(true)follows input again, letting go of a pin. - It is read in a render, and what read it is rendered again when it changes:
ui::current_pointer()in a builder,app.pointer()with the app at hand.ui::touch_form()iscurrent_pointer() == Pointer::Coarse. - A test sets it with no input,
Tree::set_pointer(Pointer::Coarse)(not pinned), and reads it withTree::pointer(). Tooling reads and sets it with the MCP toollurq_pointer.
use lurq::app::{App, Pointer};
let app = App::new();// A kiosk: every component takes its touch form, whatever moves.app.set_pointer(Pointer::Coarse);Keyboard And Focus
Section titled “Keyboard And Focus”Keyboard events go to the focused node. A press where nothing can take focus blurs it; a press on a focusable(false) element keeps it. Which elements take focus, how Tab and Shift+Tab move between them, modal focus traps, and scrolling focus into view are described in Focus And Keyboard Navigation.
Inside a component, request focus with ctx.focus(&field_ref), where field_ref is a retained core::ElementRef attached through .ref_element(field_ref.clone()). The request is applied after the render is reconciled, including when a newly mounted route creates the field, and the field is then scrolled into view. The last request wins; a ref absent from the resulting tree is ignored. field_ref.focused() subscribes the rendering component to focus changes; field_ref.focus_signal() exposes the same state for observation. field_ref.focus_visible() and field_ref.focus_visible_signal() do the same for focus-visible, the keyboard-only part of focus.
Retained input and select value signals, element refs, explicit IDs, keys and component slots keep focus attached to the same control across sibling insertion/reordering. A control that a render moves under another parent is a new node to the tree: the focus follows it where its element ref, or the value signal of its text input, finds it again (a panel of a dock layout moved to another group keeps the focus in it); its caret and its scroll come with it where it is the output of a component, which is reconciled with its own last output. Removing the focused control emits its on_blur callbacks and clears its ref, including when the whole tree is dropped. Use explicit keys or IDs for otherwise anonymous reorderable controls.
use lurq::app::events::KeyboardEvent;
Text::new("Focusable") .on_focus(|| println!("focused")) .on_blur(|| println!("blurred")) .on_key_down(|event: KeyboardEvent| { println!("key={} code={} shift={}", event.key, event.code, event.shift); })KeyboardEvent includes key, code, shift, ctrl, alt, meta, target_id, text_input_focused and composing. The keys an input method takes never reach on_key_down handlers or lurq’s own key handling, so an app that sends a message on Enter does not send when Enter confirms a composition; a press that arrives while a composition is shown has composing set, and lurq’s own defaults ignore an Enter so marked. See Input Methods.
User on_key_down handlers run before built-in keyboard defaults, so they can block text editing, focused-button activation, select navigation, modal or popup Escape dismissal, and similar defaults:
use lurq::app::events::KeyboardEvent;
TextInput::new(value) .on_key_down(|event: KeyboardEvent| { if event.key == "Tab" { event.prevent_default(); } })Taking Every Key
Section titled “Taking Every Key”An element built with .captures_keys(true) takes every key of the window while it is in the tree, before anything
else does: its own on_key_down and on_key_up handlers alone are told of a key, with focus_within true, and
nothing the window does with a key is done. Tab moves no focus, Enter presses no button, Escape closes no popup, a
focus group’s arrows and a row of menus’ Alt do nothing, nothing is typed into an input, no other element’s handler
runs, and on a Mac the accelerators of the app’s menu are not asked first. It lets go when it is built with false
or leaves the tree. It is what records a shortcut (ui::ShortcutRecorder),
while it records.
use lurq::app::{Accelerator, events::KeyboardEvent};
// recording: Signal<bool>, shortcut: Signal<Option<Accelerator>>Row::new() .tab_index(0) .captures_keys(recording.get()) .on_key_down(move |event: KeyboardEvent| { if let Some(pressed) = Accelerator::from_key_event(&event) { shortcut.set(Some(pressed)); recording.set(false); } })- An element that is disabled or inert, or in one that is, captures nothing.
- Where two capture at once, the first in the order of the tree takes the keys.
Keys Heard First
Section titled “Keys Heard First”A key is told to every element of the tree in its order, from the root down, until a handler stops it
(stop_propagation): a panel in a layer over the page, which comes after the page, hears a key after the page’s
handlers. An element built with .keys_first(true) is told first while the focus is on it or in it: it and what is in
it hear the key before the rest of the tree, and a key one of their handlers stops the rest does not hear. What the
window does with the key by default is done as before (Enter presses the focused button, Escape closes the top layer,
Tab moves the focus), unless a handler prevents it. With the focus elsewhere it is told in its place in the tree, once.
use lurq::{app::events::KeyboardEvent, components::Column};
// The panel's Enter is not also the Enter of a question under it: the panel stops it, and the focused row is pressed.Column::new() .keys_first(true) .on_key_down(|event: KeyboardEvent| { if event.focus_within && event.key == "Enter" { event.stop_propagation(); } })- A handler of the element that is told first hears what is in it next, as anywhere in the tree; to keep a key from the rest of the window after what is in it heard it, stop it from an element after them.
- Where two such elements are on the way to the focus, the outer one is told first. The list of every open tab of window tabs is one.
Editing commands: undo, redo, copy, cut, paste
Section titled “Editing commands: undo, redo, copy, cut, paste”The keys every app shares are lurq’s to know, in one place: KeyboardEvent::edit_command() says which
EditCommand a key is, if any, and lurq runs it on what has the focus. A component or an app never matches these keys
itself; it says what it does for the command.
| Command | Keys (Cmd in place of Ctrl on macOS and iOS) |
|---|---|
EditCommand::Undo | Ctrl+Z |
EditCommand::Redo | Ctrl+Shift+Z, Ctrl+Y (not on a Mac) |
EditCommand::Cut | Ctrl+X, Shift+Delete |
EditCommand::Copy | Ctrl+C, Ctrl+Insert |
EditCommand::Paste | Ctrl+V, Shift+Insert |
EditCommand::SelectAll | Ctrl+A |
No key with Alt held is a command (AltGr is Ctrl+Alt on Windows, and types letters). A letter is read as the key says it
where it is a Latin one, and by the key’s place where it says another: in a Ukrainian layout Ctrl+Z says “я” and
still takes back, Ctrl+С copies; on a German keyboard, which says Z where a US one has Y, Z is still undo.
EditCommand::accelerator() is the combination to show beside an Edit menu’s item or in a tool’s tooltip (Ctrl+Y for
redo, Cmd+Shift+Z on a Mac), as an Accelerator.
A command is run on the focused element and out from it:
- A focused text input does it to its own text where it can: takes back an edit it has, does one again, copies or cuts its selection, pastes, selects its text.
- Otherwise the handlers of the focused element, then of each ancestor, innermost first:
on_undo,on_redoandon_select_allare told anEditEvent. A handler that had nothing to do callsevent.pass_on(); an element whose handlers all passed it on did nothing, and the command goes on to the element around it. The first element that does not pass it on takes it, and no element further out is told. A copy or a cut is anon_copy’s (Copy), taken where a handler set a text, and a paste anon_paste’s (Paste). - A copy that nothing took copies the text selected on the page (a selectable text), focused or not.
With nothing focused nothing is told. A key goes to every on_key_down handler before it is a command: one that
prevents its default (an app that binds Ctrl+Z to something else) keeps it from being one, as an element that
takes every key does. A key that is a command is no other key, whether or not something took it.
use lurq::{app::events::EditEvent, components::Column};
// A pad with a history of its own, in a form whose app keeps one too: Ctrl+Z on the pad takes back its last// stroke, and with no stroke left the form's history goes back.Column::new() .on_undo(move |_: EditEvent| form_history.undo()) .child( pad .tab_index(0) .on_undo(move |event: EditEvent| { if !strokes.undo() { event.pass_on(); } }) .on_redo(move |event: EditEvent| { if !strokes.redo() { event.pass_on(); } }), )An Edit menu or a toolbar runs a command without a key: ctx.edit(EditCommand::Undo) in a render, or the
EditRunner of ctx.edit_runner() kept in a handler, and WindowHandle::edit(command) where there is no Ctx, as
in the handler of a native menu (on macOS a native item’s key equivalent takes the key before the window sees it, so
an Edit menu with Cmd+Z runs edit(EditCommand::Undo) itself). The command is run once the event that asked is
handled, on what has the focus then: after a menu that closed gave the focus back to what had it. So a tool that runs
it takes no focus itself (.focusable(false)). A paste asked for while lurq delivers synthetic input (an MCP client’s
press of the menu item) reads no clipboard.
use lurq::{app::events::EditCommand, components::Button};
let edit = ctx.edit_runner();Button::new("Undo") .focusable(false) .on_click(move |_| edit.run(EditCommand::Undo))Going back and forward
Section titled “Going back and forward”Going back is one command, as an edit is: NavigationCommand::Back and NavigationCommand::Forward, whatever asked
for it. lurq knows its sources in one place, and runs the command on the elements and then on the
router; a component or an app never matches a button or a key for it.
| Source | Back | Forward | Starts at |
|---|---|---|---|
Keys (KeyboardEvent::navigation_command()) | Alt+← (Cmd+[ on macOS and iOS) | Alt+→ (Cmd+]) | the focus |
| A keyboard’s own keys, Android’s back | Back (BrowserBack) | Forward (BrowserForward) | the focus |
| The mouse’s side buttons, on their release | MouseButton::Back | MouseButton::Forward | under the pointer |
A trackpad’s swipe between pages (on_history_swipe’s default) | fingers to the right | to the left | under the pointer |
A finger in from the edge (on_edge_pan, on_history_swipe) | from the left | from the right | where it landed |
| A browser’s buttons (the router that follows the address) | Back | Forward | the focus |
The app: ctx.history_back(), WindowHandle::history_back(), a stack’s way back, MCP | the focus |
A bracket is read as the key says it, and by its place where the layout puts a letter of another alphabet there
(a Ukrainian Mac says “х” for Cmd+[). Shift held is no command (Cmd+Shift+[ is a browser’s tab before). Alt and an
arrow go back in a text input too, as in a browser: a text input’s word moves are Ctrl’s on Windows and Linux, and on
Apple’s platforms, where Option and an arrow move by a word, the keys are Cmd’s. A key goes to every on_key_down
handler before it is a command: one that prevents its default keeps it from being one, and a key that is the command
is no other key. NavigationCommand::accelerator() is the combination to show beside a menu’s Back. In a browser the
mouse’s side buttons are the browser’s: what it does with them comes back as its back and forward.
The command goes from where it starts out to the root, innermost first. Each element’s on_history_back or
on_history_forward handlers are told a HistoryEvent (its command(), its source(), target_id and the
origin_id it started at); a handler with nothing to do calls event.pass_on(), and where every handler of an
element passed it on, it goes on to the element around. A router mounted in an element on the way goes back after the
element’s own handlers, where it can. With nothing on the way taking it, the routers mounted elsewhere in the window
are asked, the innermost first (the last in the tree’s order): a side bar beside the router has the focus, and the
router still goes back.
- From the focus: the focused element, or with nothing focused the last element in the tree’s order that has a handler for the command, which is the topmost of what is open (a dialog over the page).
- From under the pointer: the innermost element there, then from the focus where nothing there took it.
- From a part of the window (
HistoryRunner::run_in(&element_ref, command), a stack’s way back): the focused element where it is in that part, otherwise the last element of the part that has a handler, or the part.
use lurq::{app::events::HistoryEvent, ui::Dialog};
// A dialog takes going back instead of leaving the page. With it closed, the router goes back.Dialog::new(open.clone()).child( Column::new() .on_history_back(move |_: HistoryEvent| open.set(false)) .child(content),)
// A viewer goes to the picture before, and on the first one lets the page go back.viewer.on_history_back(move |event: HistoryEvent| { if !pictures.previous() { event.pass_on(); }})A button, a menu’s item or a toolbar runs the command without input: ctx.history_back() and
ctx.history_forward() in a render, the HistoryRunner of ctx.history_runner() in a handler (back(),
forward(), run(command), run_in(&part, command)), and WindowHandle::history_back() where there is no Ctx.
It runs once the event that asked is handled, on what has the focus then, as a key would: a dialog open over the page
closes on it. Navigator::back() and RouterHandle::back() move the router alone, past whatever on the page would
have taken it.
let history = ctx.history_runner();Button::new("Back").on_click(move |_| history.back())on_history_swipe is the swipe’s own event, told before the command with its direction: a handler that does
something else with the swipe calls prevent_default, and the command does not follow. One that only goes back
handles on_history_back, which hears every source alike. On a phone, a finger in from the left or the right edge
is taken as the gesture wherever something hears going back: a handler on the way, or a router anywhere in the
window.
Rich Text
Section titled “Rich Text”Text::rich(spans) is a paragraph of runs, each a RichTextSpan in a TextStyle of its own: a word in another
weight, a run in another color. It is laid out, wrapped, drawn and selected as one text.
use lurq::{ components::Text, layout::{quad::RichTextSpan, text_style::{FontWeight, TextStyle}},};
let body = TextStyle { font_size: 14.0, ..TextStyle::default() };let bold = TextStyle { weight: FontWeight::Bold, ..body.clone() };Text::rich([ RichTextSpan::new("Saved ", body.clone()), RichTextSpan::new("3 files", bold), RichTextSpan::new(".", body),]);Elements in a line
Section titled “Elements in a line”A rich text holds elements in its lines: a mention, a chip, a picture among the words, an inline link preview. Each is
an object of the text, a span that is one OBJECT_CHARACTER (U+FFFC, RichTextSpan::object(style)), and the element
the text is given for it with .object(element): the first for the first object, in the order of the text
(.objects(elements) gives several). It is in every build.
use lurq::{ components::Text, layout::quad::RichTextSpan, ui::{LinkPreview, LinkPreviewVariant},};
Text::rich([ RichTextSpan::new("The gaps are explained in ", body.clone()), RichTextSpan::object(body.clone()), RichTextSpan::new(" — read it before the review.", body),]).object(LinkPreview::new(url).variant(LinkPreviewVariant::Inline));- The element is laid out by itself, no wider than the paragraph, and the object takes its width in the line. It breaks as a word does, before it and after it and never inside, so it goes to the next line with the words around it.
- The line keeps the height of its text, and the element stands on the middle of it: one taller than the line stands over it and under it, and the paragraph draws it whole. An element that changes its size lays its line out again.
- It is an element like any other, unlike an input’s objects (
TextInput::objects), which take neither the pointer nor the focus: a press reaches what is in it, Tab stops at what it holds in the order of the text, and tooling reads it. The object’s character draws nothing. - A selection, and
Text::highlights, go across an object as across a word: its carets are where it is drawn. A copy of a selection over it gives what the element says it copies,.copy_text("[Layout](https://lurq.dev)")on it or on anything in it (the first, depth first), and nothing where it says nothing: never its character. An inlineui::LinkPreviewcopies[title](url). - An object character the text is given no element for is a character like any other.
Text Selection
Section titled “Text Selection”Plain text is not selectable by default. Opt in with .selectable(true):
lurq::components::Text::new("Drag, double-click, or triple-click this text") .selectable(true)Selectable text supports pointer drag ranges, double-click word selection, and triple-click line selection. A Shift press extends the selection from where it started (the pressed point of the last plain press, or the start of a double- or triple-click’s word or line) to the pressed point, across texts too, and a drag with Shift held goes on from there; a Ctrl press starts another selection and keeps the ones in other texts. Escape clears every selection. Selection is visual-coordinate aware, so text inside transformed parents can still be selected from the painted position.
The selection follows the glyphs on screen: hit-testing, the highlight and the copied text index the layout the text is drawn with, span by span for Markdown, and the text’s place in a box taller than it. Multiline and wrapped text render one selection highlight per selected row, covering the advances of the selected glyphs from the caret before the first to the caret after the last. On a row that the text wrapped, the whitespace and invisible marks at its end hang past it and draw nothing, so they are not highlighted; a row that ends with a line break or with the text keeps its trailing spaces highlighted. There is no marker for a line break.
Tree::selected_text() returns the selection as copying gives it: the texts drawn side by side on one line (the cells of a table row) in x order, texts stacked below each other one line each, and what a Markdown paragraph draws as presentation (a link’s isolate marks and trailing runs) left out. With the clipboard feature enabled, Ctrl+C and Ctrl+Insert copy that text to the system clipboard.
Sensitive Text
Section titled “Sensitive Text”Text the user must read but tooling must not, such as a one-time password, is marked with .sensitive():
use lurq::{components::Text, core::Sensitive};
let code = Sensitive::new(one_time_code); // a signal of Sensitive<String> stays redacted tooText::new(code.expose()).sensitive()It is laid out and painted on screen like any text. Every inspector shows ••• in its place (always three dots, whatever the length) with sensitive=true: the MCP tools (lurq_read_tree, lurq_inspect, lurq_find_by_id, lurq_find_by_class, lurq_find, and a button or other element named after it) and DevTools (element tree, inspector, snapshots). The app still reads the real text through its element handles.
Screenshots taken for an inspector cover the text: in lurq_screenshot (of a window, a region or an element) and in a DevTools node screenshot, every pixel its glyphs can paint, text shadow included, is an opaque grey bar, at the place and size the text has on screen, so the layout around it is unchanged. The bar is painted over the captured frame, so it also covers whatever the app draws over the text there. The window itself keeps showing the text. The app’s own captures (WindowHandle::screenshot, screenshot_region, screenshot_node) and Tree::painted_quads show the text, as they show the screen.
Selection follows .selectable(...) as for any text and is off by default. A selectable sensitive text can be selected and copied with Ctrl+C, which no inspector sees; to let the user copy without selecting, give them a copy button that writes the value to the clipboard itself.
.sensitive() covers the element tree only. Keep the value in a lurq::core::Sensitive<T> wherever it is held: its Debug output and its DevTools rendering are •••, so a signal, store or component props holding it shows ••• in DevTools’ signal values and history and in the props inspector, and a {:?} log line does not reveal it. Sensitive has no Display; expose() returns the value where the app uses it.
Scroll
Section titled “Scroll”Wrap content in one of the scroll components:
use lurq::{ app::events::ScrollEvent, components::{Column, ScrollVertical, Text},};
ScrollVertical::new( Column::new() .spacing(8.0) .child(Text::new("Row 1")) .child(Text::new("Row 2")),).on_scroll(|event: ScrollEvent| println!("delta: {}, {}", event.delta_x, event.delta_y))on_scroll is for what a scroll does to a list: it is not called over a list that is at its end or has nothing to
scroll. An element the wheel is for something else to (a picture it brings closer, a value it turns) listens with
on_wheel, which is called first, whatever is under the pointer and whether it can scroll, and takes the wheel with
prevent_default: then nothing is scrolled.
When the content grows, the offset stays where it is, as a page’s and a UIScrollView’s does: a list that loads
its next page in on_scroll_reach_bottom is not carried down to the page that came, which would reach the bottom
again and load the next. Two follow the end instead:
- A container that sticks to its end,
state.set_sticks_to_end(true): a chat’s or a log’s list, whose newest line is at its bottom, follows what is added there while the person reads the end, and stays where it is once they scrolled up. - One the app sent to its end (
scroll_to_bottom_pending,stick_to_bottom_if_near_end): it stays there as rows measured one by one make it grow, until the person moves it away.
Until 0.64 every offset at the end followed the end.
Stack::new().on_wheel(move |event: ScrollEvent| { event.prevent_default(); zoom.set(if event.delta_y < 0.0 { zoom.get() * 1.5 } else { zoom.get() / 1.5 });})A handler that only listens leaves the list to scroll and its on_scroll to be called as before. A finger’s scroll
is not a wheel, and on_wheel does not hear it.
Set the default scrollbar style on the theme:
use lurq::{layout::scrollbar::{ScrollBarStyle, ScrollBarVisibility}, node::color::Color};
app.theme().set_scrollbar(ScrollBarStyle { visible: ScrollBarVisibility::Auto, width: 7.0, thumb_color: Color::from_hex("#64748b"), thumb_radius: 4.0, ..ScrollBarStyle::default()});Override the scrollbar on a specific scroll component:
use lurq::{layout::scrollbar::{ScrollBarStyle, ScrollBarVisibility}, node::color::Color};
ScrollVertical::new(content) .scrollbar(ScrollBarStyle { visible: ScrollBarVisibility::Auto, width: 7.0, thumb_color: Color::from_hex("#64748b"), thumb_radius: 4.0, ..ScrollBarStyle::default() }) .scrollbar_hovered(|style| style.with_thumb_color(Color::from_hex("#94a3b8")))padding (default 2) is the gap around the bar. edge_inset overrides the gap between the bar and the edge it runs along (right for a vertical bar, bottom for a horizontal one), and end_inset the gap between each end of the track and the container’s edge; .insets(edge, end) sets both. Both are measured from the scroll container’s outer bounds, border included, so a thumb clears an 11 px rounded corner with end_inset 11, and the track is the container’s length minus twice end_inset. The thumb is track × visible / content long, at least min_thumb_length. A Reserved gutter is width plus twice the edge inset.
visible says when the bar shows. ScrollBarVisibility::Auto (the default) shows it while the content overflows, Always also while it fits, and Never (ScrollBarStyle::hidden()) paints no bar and takes no pointer for one, while the wheel, the keyboard and scroll requests still scroll. ScrollBarVisibility::OnHover (ScrollBarStyle::on_hover()) keeps the bar of overflowing content hidden until it is needed: it shows while the pointer is anywhere over the scroll container, while the content scrolls (the wheel, a scroll request, a text input bringing its caret into view) and while its thumb is dragged. Once none of these holds it stays for fade_delay (default 600 ms) and fades out over fade_duration (default 200 ms) along fade_easing (default Easing::EASE_OUT); .fade(delay, duration) sets both times, and a zero fade_duration hides it at once. A hidden bar is not painted and takes no pointer, so what lies under its place gets the hover and the press; a shown one, fading too, behaves as an Auto bar. The pointer coming straight onto a hidden bar’s place shows the bar, which takes the pointer from its next move. OnHover works the same for scroll containers, VirtualizedList and a multiline TextInput; with ScrollBarPlacement::Reserved the gutter stays reserved while the bar is hidden. The fade is a change of opacity, which reduced motion keeps; an app that wants none sets fade_duration to zero.
thumb_inset is the gap between the lane of the bar (width across) and its thumb, on every side: the thumb is width less twice the inset across, and it moves along the track less twice the inset; where it is, what takes the pointer and how far a drag takes the content all measure by it. thumb_radius rounds the thumb, track_radius the lane where it has a track_color. thumb_hovered_color is the thumb of the bar under the pointer and thumb_pressed_color the thumb that is dragged (the hovered color where it has none), each a BackgroundColor: a color, or a role of the palette that follows light and dark (BackgroundColor::Palette(PaletteColor::MutedForeground)). Each bar of a container that scrolls both ways has its own: the one under the pointer changes, not the other. Where both of its bars are there, each track ends before the other’s lane (its width and edge inset), so the two thumbs keep out of the corner where they meet. style.thumb_when(&palette, hovered, pressed) says what a thumb is drawn in, and ScrollState::hovered_bar() and dragged_bar() which bar is under the pointer and which is dragged.
The design system’s theme (ThemeDefinition::neutral(), what an app has when it sets none) has the design’s bar: a lane of 8 with a thumb of 6 in it (thumb_inset 1), round (thumb_radius 3), in Ring, MutedForeground under the pointer and while it is dragged, 2 from the edge and from the ends. ScrollBarStyle::default() is the engine’s bar: its thumb is as wide as its lane, 8, and has no color of its own under the pointer. ThemeDefinition::legacy() keeps it with 0.62’s thumb, black at a third of its opacity, where a style that sets no color is drawn in Ring. On iOS both are the platform’s indicator.
.scrollbar_hovered(...) receives the effective style, so it applies to either the theme default or the component override. It applies while the pointer is over the area where the scrollbar takes the pointer, described below.
Where a scrollbar takes the pointer depends on whether it visibly owns its lane. A Reserved gutter, or an overlay bar with a painted track (a track_color that is not fully transparent), takes the whole lane: the track along its length and, across it, the bar plus 4 px on each side (or the edge inset, if larger), so it covers the gutter and reaches the container’s edge. A plain overlay bar, with the default transparent track, takes only its thumb plus 4 px around it on every side; the rest of the lane belongs to the content, so a trailing button or a menu option next to the bar keeps its clicks and hover. A bar shown by ScrollBarVisibility::Always while the content fits has nothing to scroll and takes no pointer.
Where a scrollbar takes the pointer, a press reaches no content underneath: none of its handlers, buttons, inputs or sliders, and no text selection. The scroll container itself and its ancestors still receive the press. A press on the thumb drags it. A press on the track of a bar that owns its lane pages one viewport toward the press, once per press (holding the button does not repeat), on Windows and macOS alike. Either way the scrollbar holds the pointer until the release, which clicks nothing. Where two bars overlap, the one painted on top wins: an outer scroll container’s bar over the bars of the containers inside it. The two bars of a two-axis scroller do not overlap: each track ends before the other’s lane, so a press in the corner where they meet is neither bar’s, and a press at the end of either track pages that one. The mouse wheel and Shift+wheel are unaffected.
A scroll container that has the focus itself (one given a tab_index, as a ui::ScrollArea with a label is) scrolls with the keys, as a browser scrolls a focused region: Up and Down by 40, Left and Right likewise across, PageUp and PageDown, Space and Shift+Space by what it shows, Home and End to its start and its end, once no handler took the key. A control inside it keeps its keys, and so does a multiline TextInput, which scrolls its own text.
To what reads the tree (the MCP server’s lurq_read_tree and lurq_inspect), each bar of a scroll container whose content overflows is a scrollbar with its value: the attributes scrollbar_vertical and scrollbar_horizontal, how far the content is scrolled along that way, from 0 at its start to 100 at its end.
ScrollEvent includes x, y, delta_x, delta_y, phase, source and target_id.
What a scroll tells
Section titled “What a scroll tells”A container’s handlers hear its content start to move, every move, and the content come to rest:
use lurq::app::events::{ScrollEvent, ScrollSource};
ScrollVertical::new(feed) .with_scroll_state(state.clone()) .on_scroll_start(|_: ScrollEvent| println!("it moves")) .on_scroll({ let state = state.clone(); move |event: ScrollEvent| { // An event with no delta comes after the content moved: the offset read here is what is drawn. if (event.delta_x, event.delta_y) == (0.0, 0.0) { println!("{} moved it to {}", event.source.as_str(), state.scroll_y()); } } }) .on_scroll_end(|event: ScrollEvent| println!("at rest, after {:?}", event.source)) .on_page_change(|page: usize| println!("page {page}"))on_scrollafter every move. A wheel’s, a touchpad’s and a finger’s event is heard once with its delta, before anything moves, where a handler can prevent the scroll. A finger’s is followed by an event with no delta for the container that moved, once its content is where the finger took it. So is every step of what goes on by itself: a wheel’s notch drawn over several frames, a finger’s momentum, a list on its way to a page, a scroll to the top, a drag of the bar’s thumb, an autoscroll. The last of them comes with the content where it stays. A handler that readsScrollState::scroll_y()reads it in the events with no delta. A touchpad, and a wheel that is not animated, move the content at once and have the one event, before the move: the offset after it is read at the next layout (after_layout, an element’s observer).on_scroll_endat rest. Called once, when nothing moves the content any more: after a finger lifted and the momentum it left has stopped, the list has come to its page, and content pulled past an end has sprung back; when a wheel’s notch has brought the content where it sent it; when the bar’s thumb is let go; when an autoscroll ends. A finger that lifts with nothing left to do ends the scroll at the lift. A finger that catches content on its way holds it: the scroll is not over until it lets go. Through 0.64 a finger’s lift was the end, with the momentum and the way to a page still to come, and the momentum was a scroll of its own with a start and an end.on_scroll_startis the other end of it: once for a finger and all it leaves the content doing.event.sourceis what moves the content:ScrollSource::Finger,Wheel(a mouse’s wheel and a touchpad),Momentum,Snap(a list on its way to a page),Scrollbar,Autoscroll, andCodefor what the app asked for (ctx.scroll_to_top_of,ctx.scroll_state_to, a tap on a phone’s status bar).source.as_str()is its name in a log.- A touchpad and a wheel with no notches move the content at once and tell no end of their own, unless the
platform tells the gesture’s (macOS). An offset the app sets (
set_scroll, a scroll queued for the next layout, an element brought into view), the keys of a focused container and a layout that holds the offset to shorter content move it without any of the three events. The page follows them all: see below.
The page. A page is as long as the container’s viewport. ScrollState::page() is the page nearest the
offset that is drawn, so it changes half way between two. An app that shows one page at a time, a feed whose
current page plays its video, goes by the page the content came to rest on:
let state = ScrollState::new();state.set_paging(true); // a finger scrolls it a page at a time
// In a render: rendered again when the content comes to rest on another page.let (_, page) = state.page_signal().get();
// Or as an event, on the container.ScrollVertical::new(pages) .with_scroll_state(state.clone()) .on_page_change(move |page: usize| current.set(page))ScrollState::rested_page()is the page the content last came to rest on, along each axis. It does not change while a finger drags the content, during its momentum or while a wheel’s notch is drawn: it changes when they are over, and at once for what moves the content at once (a touchpad, the keys,set_scroll).- A list on its way to a page is on it when it has arrived to the eye. The spring that brings it there is
within a fiftieth of a page of it 0.42 s after a lift at rest a page away, and goes on for a quarter of a
second more before it is still: the page is told at the first, with
on_scrollgoing on for the steps that are left andon_scroll_endat the second. What a feed starts onon_page_changestarts as the page stands there, and not a quarter of a second later. A finger that catches the list in those last pixels and takes it back has the page told again where it rests. ScrollState::page_signal()is the same as a signal, for a render, andon_page_changeis called when it changes, with the page along the way the container scrolls (down, where it scrolls both ways). It follows every source, the app’s ownset_scrollamong them, and needs no paging: any container has pages.ScrollState::target_page()is the page the content is going to: the one a list that scrolls by pages goes on to once the finger lifted, known at the lift, before anything moved; the one a wheel’s notch ends on; andpage()otherwise. A feed that wants its next video ready opens it when the target changes.ScrollState::moving()says whether something moves the content or holds it.
The lurq::scroll tracing target says, at debug, when a finger’s scroll starts, the page a list is sent to at
the lift (snapping to page), each change of the page, and where the content comes to rest, with what moved
it.
The default movement of a wheel or a trackpad scrolls one container on each axis, the innermost under the pointer that can still move that way: see Scroll containers inside one another.
The mouse wheel
Section titled “The mouse wheel”A notch of a mouse’s wheel scrolls 40 logical pixels. The content is not drawn there in the next frame: it is animated there over 150 ms, fast at first and slowing into its place, as a browser scrolls a page. A notch that comes while the content is on its way adds to where it is going, so a wheel that is spun covers as much as it did before and stops as soon after its last notch as after one; a notch the other way turns the content round at once.
// Where the content is drawn now, and where the wheel is taking it.let drawn = state.scroll_y();let (_, going_to) = state.scroll_target();
// A notch scrolls at once, in every window that draws with this theme.app.theme().set_smooth_scroll(false);ScrollState::scroll_x()andscroll_y()are the offset that is drawn, at every step.ScrollState::scroll_target()is where the wheel is taking it, and the offset itself when nothing is on its way.- An
on_scrollhandler hears the wheel’s event once, with its delta, before anything moves, and can prevent the scroll as before. It then hears one event with a zero delta for every step, after the content moved: a handler that reads the offset there reads what is drawn.on_scroll_reach_topandon_scroll_reach_bottomrun when the content gets there, not when the wheel turns. AVirtualizedList, sticky elements and whatever else is laid out from the offset follow every step. - Only a mouse’s notches are animated. A touchpad and a wheel that turns without notches tell their travel in small parts, which move the content with the fingers as before: a delta in pixels, and on Windows and X11 a part of a line. A finger on a touch screen has its own momentum. A browser tells every wheel in pixels: a lurq app that runs in one takes a delta that comes to a whole number of notches for a mouse’s and animates it, and scrolls every wheel at once on macOS, where a notch has no distance of its own.
- Anything else that scrolls the container stops the animation where the content is, and has its way:
set_scroll, a scroll queued for the next layout (set_scroll_pending,scroll_to_bottom_pendingand the rest), an element scrolled into view, a drag of the scrollbar’s thumb or a press on its track, a touchpad, a finger. Content that keeps its place while what is above it changes, a list that takes rows in above what is shown, keeps it and the animation goes on from there. A notch that takes the content to its end follows the end if the content grows on the way, and stays where it lands after. - With reduced motion a notch scrolls at once, and so it does with
Theme::set_smooth_scroll(false). Smooth scrolling is on by default. Like reduced motion it is the app’s setting and not part of aThemeDefinition. - While the content is on its way the window has a running animation:
Tree::has_active_timeline()is true and the shell draws a frame at every refresh, and none once the content is where it was going. - Synthetic input’s
wheel(SyntheticInput::wheel, the MCP server’swheel) is a mouse’s wheel and is animated too. A test that drives aTreeitself callsTree::wheelfor a notch andTree::scrollfor a touchpad’s delta, which moves the content at once.
The handlers of an event with a delta run before the default scroll movement. Call prevent_default() to observe a wheel/scroll event without moving the scroll container:
use lurq::app::events::ScrollEvent;
ScrollVertical::new(content) .on_scroll(|event: ScrollEvent| { event.prevent_default(); })What takes the pointer
Section titled “What takes the pointer”An element takes the pointer wherever its box is, whether or not anything is drawn there: a press, a hover, a
finger’s swipe and the wheel go to the innermost element under the point and then to what is around it. In a
Stack a child lies over the children before it, and where it is hit nothing under it is: a layer as large as
the stack takes every press and every swipe of the stack, also where it is empty.
HitTestBehavior says otherwise for one element:
use lurq::node::HitTestBehavior;
Stack::new() .child(list) // scrolls under the layers .child(shade.pointer_events_none()) // drawn, and nothing to the pointer .child(buttons_at_the_edges.hit_test(HitTestBehavior::ContentOnly)) // its buttons take the pointer, its room does notHitTestBehavior | The element | What is in it |
|---|---|---|
Auto (the default) | Takes the pointer over all of its box | Takes it first, where it is |
ContentOnly | Takes nothing itself: its box is clear to the pointer | Takes it as before. Where something in it is hit, the element is hit with it, so its handlers hear that and it covers what is under it there |
None (.pointer_events_none()) | Takes nothing | Takes nothing either: the whole subtree is clear to the pointer |
- Layers over a list. A feed of pages with the app’s layers over each page (a shade behind the words, a
column of buttons, a title) scrolls only where no layer is, unless the layers let the swipe through: a finger
that lands on a layer scrolls what that layer is in, and a full-size layer is in the stack, over the list and
not in it. Give what is only drawn
.pointer_events_none()and what holds buttons.hit_test(HitTestBehavior::ContentOnly): the swipe then lands on the list everywhere but on the buttons. One that starts on a button does not scroll the list: the button lies over the list and is not in it, as a button in a row of the list would be. ContentOnlyis for a wrapper that only places things: a row that spreads two buttons to the ends of a bar, a column that centers a play button over a picture.ui::VideoPlayergives the app’s own layer over its picture this behavior, so a press beside the app’s controls reaches the picture.- It is about the pointer alone. An element that takes none still takes the keyboard’s focus if it can, is read by
tooling, and is drawn;
.inert(true)takes an element and all it holds out of the pointer and the focus both. - A scroll container’s bar, a disabled element and an element with no handlers are not special here: the first takes the pointer where its thumb is, the second is hit and takes nothing, the third is hit and passes the event on to what is around it, which is not what is under it in a stack.
Event Control
Section titled “Event Control”MouseEvent, KeyboardEvent, and ScrollEvent share the same control methods:
| Method | Effect |
|---|---|
event.prevent_default() | Blocks runtime default behavior for that event. |
event.default_prevented() | Returns whether a handler already prevented the default. |
event.stop_propagation() | Stops later handlers for the same dispatched event path. |
event.propagation_stopped() | Returns whether propagation has been stopped. |
event.stop_immediate_propagation() | Stops later handlers on the current node and later nodes. |
event.immediate_propagation_stopped() | Returns whether immediate propagation has been stopped. |
Propagation control and default-action control are separate. Use stop_propagation() when another handler should not see the event. Use prevent_default() when handlers may still run, but the runtime should not perform the event’s built-in action.
use lurq::app::events::MouseEvent;
Rect::new(100.0, 40.0) .on_click(|event: MouseEvent| { event.stop_propagation(); })Common defaults that can be prevented include:
- focusing an input from mouse down,
- text input editing from key down,
- focused button activation from
EnterorSpace, - single-line text input submit or blur on
Enter, - select keyboard navigation,
- modal or popup Escape dismissal,
- form submit from buttons or keyboard,
- popup outside-click dismissal,
- scroll container movement.
Public capture-phase handlers are not part of the general event API yet. The current model keeps dispatch simple: handlers receive the event, can stop later dispatch with propagation methods, and can block runtime defaults with prevent_default().
Inputs
Section titled “Inputs”Inputs are controlled by signals.
let checked = ctx.signal(false);let volume = ctx.signal(50);let name = ctx.signal(String::new());
Column::new() .child(lurq::ui::Checkbox::new("Subscribe").bind(checked.clone())) .child(lurq::components::Slider::new(volume.clone()).range(0, 100)) .child(lurq::components::TextInput::new(name.clone()).placeholder("Name"))These are the engine’s controls, with no look but the theme’s roles; the design system’s (lurq::ui::Slider, lurq::ui::Input, see Design System) are built on them and are what an app normally wants.
Input updates write back to their signals, which rerenders the owning component.
TextInput::on_input runs before a built-in text edit is applied. The event carries the input’s Signal<String> as event.value and the key that caused the edit as event.keyboard. Mutate the signal directly for custom input behavior, and call event.prevent_default() to cancel the built-in edit for that action:
use lurq::app::events::TextInputEvent;
TextInput::new(command.clone()) .on_input(|event: TextInputEvent| { if event.keyboard.key == "Tab" { event.value.set("/play ".to_owned()); event.prevent_default(); } })Checkbox Styling
Section titled “Checkbox Styling”This is the engine’s checkbox node, lurq::components::Checkbox, which is deprecated for an app since 0.63 in favour of lurq::ui::Checkbox, themed by its recipe: see the migration guide. It still compiles, with a warning.
Checkboxes accept normal element modifiers such as .size(), .background(), .border_inside(), .rounded(), .cursor(), .hovered(), and .focused(). Generic .background() styles the unchecked box. Checked visuals use checkbox-specific styles so the checked state can have its own color or indicator. .box_focused(...) styles the box while the checkbox has keyboard focus (focus-visible: Tab or a key press, not a click), checked or not; it changes paint only.
A checkbox the app has not styled takes its fill from the theme, through the recipe the theme keeps for the engine’s checkbox (engine_checkbox, by ui::CheckboxPart::Box and ui::CheckboxState::Checked): the box is Background and the checked box Primary, and under ThemeDefinition::legacy() the roles of 0.62, SurfaceInput and Accent. A part the app styles without a fill paints none, like a button or text input without a background: .box_part(...) without background leaves the unchecked box unfilled, and .checked_box(...) without one the checked box (its border and indicator still paint). A checked box whose checked_box part the app did not set keeps the unchecked part’s fill, or the theme’s checked fill. Generic .background() still fills the unchecked box.
use lurq::{components::Checkbox, core::Signal, node::color::Color};
let enabled = Signal::new(true);
Checkbox::new(enabled) .size(20.0, 20.0) .background("#ffffff") .border_inside(1.0, Color::from_hex("#94a3b8")) .rounded(4.0) .checked_box(|style| { style .background("#2563eb") .border_inside(1.0, Color::from_hex("#1d4ed8")) .rounded(4.0) }) .box_hovered(|style| style.border_inside(1.0, Color::from_hex("#38bdf8"))) .checked_box_hovered(|style| style.background("#1d4ed8"))With the image feature enabled, checked boxes can render an indicator image centered inside the box:
use lurq::{components::Checkbox, images::ImageData};
let check = ImageData::from_file("assets/check.png").unwrap();
Checkbox::new(enabled) .checked_box(|style| { style .background("#16a34a") .indicator_image(check) .indicator_size(12.0, 12.0) .indicator_contain() })With image, the indicator can come from the app resource loader:
Checkbox::new(enabled) .checked_box(|style| style.indicator_image("ui/check.png").indicator_size(12.0, 12.0))Text Input Editing
Section titled “Text Input Editing”Plain Text can align content inside its own box:
use lurq::{layout::Alignment, node::dimension::Dimension};
Text::new("No endpoints yet") .width(Dimension::Pct(100.0)) .text_align(Alignment::Center)TextInput keeps editing state internally while the string value remains signal-owned. Clicking focuses the input and places the caret. Dragging selects a range; double-click selects a word; triple-click selects a line. Multiline inputs support vertical caret movement and per-row selection highlights. ArrowUp and ArrowDown move the caret one laid-out row, so a soft-wrapped paragraph is crossed a wrapped line at a time; above the first row the caret goes to the start, below the last to the end. A run of them keeps the column it started from, so a short row on the way does not pull the caret to its end. After a value that ends with a line break, the end is the empty row below the last laid-out row.
A multiline input whose text needs more rows than its rows(min, max) allow scrolls its own text. Its caret’s line stays in view while the person types or moves the caret. The wheel, a trackpad and its scrollbar move the text within it, and that scroll stays until the next edit or caret move brings the caret back; deleting lines brings the text back to its first line once it fits. While the text overflows, the input shows a vertical scrollbar along its right edge, styled and placed like a scroll container’s: the theme’s ScrollBarStyle, or the input’s own .scrollbar(...) and .scrollbar_hovered(...), with edge_inset and end_inset measured from the input’s outer bounds, whatever its padding. The padding is the text’s inset and scrolls with the text, as in a browser’s textarea: scrolled down, the text runs through the top padding, and the bottom padding shows under the last line at the end; the caret’s line is kept in view inside the padding. Its thumb drags and a press on its track pages, and the pointer over it shows the default cursor, whatever cursor the input sets. A bar placed ScrollBarPlacement::Overlay (the default) runs over the text; one placed ScrollBarPlacement::Reserved gets a lane of its own at the input’s right edge, as wide as the bar and its edge inset on both sides (the wider of its resting and hovered styles), and the text wraps short of it, the right padding between them. Like a reserved scroll container’s gutter, the lane stays while the text fits, so the text does not re-wrap when it starts or stops overflowing. A wheel over an input whose text fits, or one already at the end the wheel moves to, passes on to the scroll containers around it. A wheel that brings the text to its end moves the text alone, the rest of that event included: an input is the innermost of the scroll containers it is in.
Lines, the caret and selections follow the font’s metrics, not the ink of the glyphs shown: a multi-line input’s lines sit in line boxes of the style’s line_height from the top of the content box (VerticalAlign::LineBox), so a line does not move when a taller glyph is typed. The caret is as wide and as high as the theme’s caret says (the theme’s caret): 1.5 wide and nine sevenths of font_size high in the design’s theme (18 in type of 14), 1 wide and font_size high in ThemeDefinition::legacy() and bare(). Among the rows of a multiline input it is never higher than its row; in a single-line input it may be, up to the box the text is in. A selection covers the font’s ascent and descent. Both are centered in the line box, so the leading of a relaxed line_height stays unpainted. A single-line input scrolls the whole of the caret into view, and a multiline one whose lines do not wrap is as wide as its longest line and the caret after it. The caret starts at its insertion point; at the start of a left-aligned line it ends there instead, so it never covers the first glyph of the value or the placeholder (unless an ancestor clips right at that edge). A focused input’s caret blinks every 530 ms unless its caret_mode or the theme’s is CaretMode::Persistent; an idle window wakes only at each toggle.
An input draws two marks an app gives it beside its text. squiggles(InputSquiggles::new(ranges)) draws a wavy line under each range of the text, bytes of the value as it is when the input is built: what a spelling checker marks. The lines are under the band of the text on every row a range is on, in the theme’s Destructive unless .color(..) says another; the app finds the ranges again after an edit, and a masked input draws none. ghost(InputGhost::new(text)) draws a suggestion after the end of what is typed, in the input’s type and the placeholder’s color (or .color(..), at .opacity(..)), while the input has the focus, holds text, and has the caret at the end with nothing selected. It is no part of the value: the app puts it there when its key is pressed (TextInputController::replace_selection). An input with tokens or styled spans draws no ghost.
use lurq::{ app::theme::PaletteColor, components::{InputGhost, InputSquiggles, TextInput},};
TextInput::new(note.clone()).multiline().squiggles(InputSquiggles::new([2..10]));TextInput::new(command.clone()) .single_line() .ghost(InputGhost::new("n --release").color(PaletteColor::MutedForeground).opacity(0.7));select_on_focus(true) has all an input’s text selected as it takes the focus, so that what is typed takes its place: a name being renamed, a cell being edited. A press that brings the focus puts the caret where it is, as in any input.
Single-line inputs can align value and placeholder text inside their content box:
use lurq::layout::text_style::TextAlign;
TextInput::new(endpoint.clone()) .placeholder("Connect to an endpoint to get started.") .single_line() .text_align(TextAlign::Center)Password inputs can hide their contents with .mask(), which renders a bullet (•, U+2022) for each character instead of the typed text. Use .mask_char(...) for a custom mask character, such as .mask_char('\u{25cf}') for a WinUI-style heavy dot (●) or .mask_char('*') for the previous default. Use .unmask() to clear masking:
TextInput::new(password.clone()) .placeholder("Password") .single_line() .mask()
TextInput::new(pin.clone()) .single_line() .mask_char('#')
TextInput::new(visible_secret.clone()) .mask() .unmask()Masking changes displayed text and built-in node inspection. The signal value, clipboard copy/cut, and caret and selection behavior all operate on the real text.
Built-in MCP and DevTools inspection returns the displayed mask and masked=true, including tree text, lookup/find data, shape details and set-value replies. Underlying editing/form values remain intact. Typed TextInputHandle::mask() and is_masked() expose the configuration; direct application access to value() still returns the real value. An empty masked field can still display its ordinary placeholder.
Mask glyphs use the normal text shaping and font fallback chain. If the selected font lacks U+2022, the shaper searches the loaded and system fallback fonts for the bullet. If no available fallback contains it, the font’s missing-glyph marker may appear; Lurq does not substitute *. Load a font containing U+2022 or choose a supported custom mask in that case.
Keyboard editing supports character insertion, Backspace, Delete, arrow keys, Home, End, Ctrl+A, Ctrl+Z, Ctrl+Y, and Ctrl+Shift+Z. Hold Shift with movement keys to extend the selection; hold Ctrl with horizontal movement to jump by words.
With the clipboard feature enabled, text inputs also support Ctrl+C, Ctrl+X, Ctrl+V, Ctrl+Insert, Shift+Insert, and Shift+Delete (Cmd for Ctrl on macOS). Without clipboard, those shortcuts do not read or write the system clipboard. In a browser a paste arrives a turn of the loop after its shortcut, once the browser has answered, and carries text only; see Web.
Lines Of Code
Section titled “Lines Of Code”A multiline input’s lines wrap at its width unless .wrap(false) says otherwise: then it is as wide as its longest line, and what holds it scrolls sideways. .line_gutter(LineGutter::new(style)) draws the numbers of its lines in its start padding, each at the first row of its line as the input laid it out (after the rows a wrapped line took), right-aligned gap before the text, and a band across the input behind the lines it picks out (.marked(lines, color)), over every row of a wrapped line. The app makes the start padding as wide as the numbers need. The numbers and the bands are neither selected nor copied. A read-only input of code is what ui::CodeBlock is made of.
use lurq::{ app::{events::TextInputEvent, theme::PaletteColor}, components::{LineGutter, TextInput},};
TextInput::styled(code.clone(), mono) .multiline() .wrap(false) .padding_left(40.0) .line_gutter(LineGutter::new(mono.clone()).color(PaletteColor::MutedForeground).marked([3], PaletteColor::Highlight)) .on_input(|event: TextInputEvent| event.prevent_default()); // read onlyA paste into a text input delivers one PasteEvent before the text is inserted: Ctrl+V, Shift+Insert, an Edit menu’s Paste (ctx.edit(EditCommand::Paste)), a WindowHandle::paste_from_clipboard() request (for an app’s own Paste menu item or context menu) and Tree::paste(content) all go through it. The event carries everything the clipboard holds, as lurq::clipboard::read_clipboard reads it: text, an RGBA image (a screenshot) and file paths (files copied in Explorer or Finder), any of them at once. Handlers run on the input first and bubble to its ancestors (stop_propagation() ends that); unless one calls prevent_default(), the text is inserted at the caret. An image or files without a handler do nothing.
use lurq::{app::events::PasteEvent, components::TextInput};
TextInput::new(draft.clone()) .multiline() .on_paste(move |event: PasteEvent| { if let Some(image) = event.image() { attachments.update(|list| list.push(Attachment::png(image.to_png().unwrap()))); event.prevent_default(); // no text goes into the input } else if !event.files().is_empty() { attachments.update(|list| list.extend(event.files().iter().cloned().map(Attachment::file))); event.prevent_default(); } else if event.text().is_some_and(|text| text.len() > 4_000) { attachments.update(|list| list.push(Attachment::text(event.text().unwrap()))); event.prevent_default(); } // plain text pastes as always })PasteEvent::kinds() tells which of text, image and files the clipboard holds; content() gives the whole ClipboardContent. The handler runs inside the input’s delivery, so is_synthetic_input() tells an MCP client’s paste from a person’s. A synthetic Ctrl+V (lurq_interact key, an applied SyntheticInput::key_down) never reads the OS clipboard: it is refused, and a synthetic paste carries its own content instead (SyntheticInput::paste(content), the MCP paste action). See Testing.
A styled input with kinds of paragraphs that keeps its formatting through the clipboard (rich_clipboard(true), feature markdown; the design system’s rich text editor has it) pastes ClipboardContent::markdown_content(), the Markdown a lurq input copied beside the text (PasteEvent::markdown()), or a text that reads as Markdown, with its marks and kinds. Any other input pastes the text.
A copy or a cut on a focused element that is not a text input (a cell of a data grid, a canvas) delivers one CopyEvent: Ctrl+C and Ctrl+Insert copy, Ctrl+X and Shift+Delete cut (Cmd on macOS, in any layout), and so do an Edit menu’s Copy and Cut. Handlers run on the focused element first and bubble to its ancestors; one says what goes on the clipboard with event.set_text(..) (a later call takes the place of an earlier one), and the engine writes it once they have run. event.is_cut() tells a cut, whose handler takes away what it copied. With no text set nothing is written, and a selectable text with a selection is copied as where no on_copy handler is on the way.
use lurq::{app::events::{CopyEvent, PasteEvent}, components::Row};
Row::new() .tab_index(0) .on_copy(move |event: CopyEvent| { event.set_text(board.selection_as_text()); if event.is_cut() { board.remove_selection(); } }) .on_paste(move |event: PasteEvent| { if let Some(text) = event.text() { board.insert_text(text); } })A press of a control that copies (the copy button of a code block) puts its text there with window.copy_to_clipboard(text) on the window’s handle (ctx.window()): it is written once the handler returns, or at the next pass where it was asked outside an event, where a copy shortcut writes.
Ctrl+V and Shift+Insert on such an element deliver a PasteEvent to it and its ancestors where one of them has an on_paste handler, as to a text input, with nothing inserted by default; Tree::paste(content) does the same. The copy writes the OS clipboard (feature clipboard), or what a test installs with tree.set_clipboard_writer(Some(Arc::new(writer))), a lurq::app::ClipboardWriter with write_text(&str), which a text input’s copy goes to as well; a copy that keeps its formatting calls write_rich(text, markdown), which writes the text unless the writer keeps the Markdown too, and a test’s ClipboardReader answers read_markdown(text) with it.
An app says once where all of its copies go, in every window: app.set_clipboard_writer(Some(Arc::new(writer))), and app.set_clipboard_reader(..) for what its pastes read. Every copy goes there in place of the OS clipboard: a copy shortcut in a field, the copy button of a code block (a Markdown document’s too), a table’s copy, window.copy_to_clipboard. A copy button says it copied, or could not, by what write_text answers. A QA copy of an app or a gallery gives a clipboard of its own here, so it never touches the person’s. A test’s writer on its tree stays over the app’s.
Input Methods
Section titled “Input Methods”Text inputs take input method (IME) composition on Windows and macOS: Japanese, Chinese and Korean input, dead keys and the macOS accent menu. While a text input that is not masked has focus, the winit shell lets the window’s input method compose and places its candidate window at the input’s caret; password fields (.mask()) take no composition, like the platforms’ native ones.
- While composing, the input shows the composition text at the caret, in place of the selection, underlined in the text colour by a line as thick as the theme’s caret says (
ThemeCaret::composition_line: 1.5 in the design’s theme, 1 in the legacy one), with the caret where the input method puts it. The value does not change andon_inputdoes not fire until the composition is committed. - The commit inserts the text like typing:
on_inputhandlers run first, with aKeyboardEventwhosekeyis the committed text, whosecodeis empty and whosecomposingis set, and can prevent it. A cancelled composition leaves the value as it was. Moving focus away cancels a composition. - The input method takes the keys it uses, including the
Enterthat confirms a composition: Windows reports each as a press of the key"Process"with the physical key as itscode, macOS does not report it at all. These presses reach neitheron_key_downhandlers nor lurq’s defaults (newline, form submit, button activation); their releases reachon_key_uphandlers withKeyboardEvent::composingset. A key the input method passes on while a composition is shown, such as a space after a Korean syllable, arrives as usual withcomposingset and is handled like any key, so nothing is lost and a composition the platform never ends holds no key back. The exception isEnter: one that arrives markedcomposingreacheson_key_downhandlers, but no lurq default acts on it (form submit, button or select activation, newline, blur), as on the web, where apps ignore anEnterwithisComposing. A form exposes no key handler, so it could not tell such anEnterapart itself; once the composition is committed,Entersubmits as usual. A new input method session (ImeEvent::Enabled) or a focus change ends a composition left behind.
use lurq::app::events::KeyboardEvent;
TextInput::new(draft.clone()) .multiline() .on_key_down(move |event: KeyboardEvent| { // The confirming Enter never arrives; a press passed on while composing is marked. if event.key == "Enter" && !event.shift && !event.composing { event.prevent_default(); send(); } }) .on_key_up(|event: KeyboardEvent| { if event.composing { return; } // ... })Tree::is_composing() and TextInputHandle::composition() report a composition in progress. A shell other than winit forwards its platform’s input method events through Tree::ime(ImeEvent) and asks Tree::ime_allowed() and Tree::ime_cursor_area() (logical pixels) whether, and where, the input method should compose; tests drive composition the same way (see Testing).
Slider Styling
Section titled “Slider Styling”Slider::new uses Signal<i32>. Pointer input maps the track position into the range, and the default keyboard step is 1. Use Slider::new_f32 with Signal<f32> and .range_f32(min, max) for fractional values; .step(value) controls snapping and keyboard increments.
An unstyled slider takes its fills from the theme, through the recipe the theme keeps for the engine’s slider (engine_slider, by ui::SliderPart::Track and Thumb): the track Border, the thumb Primary, and under ThemeDefinition::legacy() the thumb in 0.62’s Accent (generic .background() fills the track). theme.ui.patch::<Slider>(..) restyles every unstyled slider. A .track(...) or .thumb(...) part without a background paints no fill for that part.
let gain = lurq::core::Signal::new(0.5_f32);lurq::components::Slider::new_f32(gain).range_f32(0.0, 1.0).step(0.05);.on_change(|low, high| ..) is told each change a person makes, as it is made: a drag as it moves, a press on the track, a key, a value set by an MCP client. .on_change_end(|low, high| ..) is told when such a change is over: the drag let go, the press or the key done. Both are given the low value and the high one; a slider of one value gives its value twice. Neither is told what the app sets on the signal, nor a range or a step that snaps the value. Each call adds a handler.
let gain = lurq::core::Signal::new(0.5_f32);lurq::components::Slider::new_f32(gain) .on_change(|value, _| println!("now {value}")) .on_change_end(|value, _| println!("settled on {value}"));The slider frame still accepts normal modifiers like .width(), .height(), .cursor(), and .focused(). Track and thumb visuals are styled separately with SliderPartStyle; a part’s style can have an .outline(Outline), a ring around the part that changes no size; .thumb_focused(...) styles the thumb while the slider has keyboard focus (focus-visible: Tab or a key press, not a click or drag) and changes paint only.
use lurq::{components::Slider, core::Signal, node::color::Color};
let value = Signal::new(68);
Slider::new(value) .range(0, 100) .width(260.0) .height(34.0) .track(|style| { style .size(220.0, 2.0) .background("#334155") .rounded(1.0) .border_center(1.0, Color::from_hex("#64748b")) }) .track_hovered(|style| { style .height(4.0) .background("#475569") .border_center(1.0, Color::from_hex("#93c5fd")) }) .thumb(|style| { style .size(12.0, 12.0) .background("#f97316") .rounded(6.0) .border_inside(2.0, Color::from_hex("#0f172a")) }) .thumb_hovered(|style| { style .size(14.0, 14.0) .background("#fb923c") .rounded(7.0) .border_inside(2.0, Color::from_hex("#f8fafc")) })The track and thumb support width, height, background color, border, corner radius, image backgrounds, and hover overrides. Corner radius accepts f32 or RadiusSize. Hover dimensions are included in the slider’s preferred size, so a larger hover thumb does not resize surrounding layout when the pointer enters.
The thumb is centered on the track line, not on the slider frame. A 2px track with a 10px or 14px thumb keeps the thumb vertically centered on that thin track.
Image-backed slider parts use the same image feature as node background images:
use lurq::{components::Slider, images::ImageData};
let track = ImageData::from_file("assets/track.png").unwrap();let thumb = ImageData::from_file("assets/thumb.png").unwrap();
Slider::new(value) .track(|style| style.height(2.0).background_image(track).background_cover()) .thumb(|style| style.size(16.0, 16.0).background_image(thumb).background_cover())With image, pass resource paths instead:
Slider::new(value) .track(|style| style.background_image("ui/slider-track.png").background_cover()) .thumb(|style| style.background_image("ui/slider-thumb.png").background_cover())Vertical And Range Sliders
Section titled “Vertical And Range Sliders”.orientation(SliderOrientation::Vertical) (or .vertical()) runs the track up the slider: the least value is at the bottom, a drag goes along the height, and the up and down arrows move it as the right and left ones do. The parts are laid along the height, so a vertical track’s style gives its thickness as width and leaves height to the slider’s, and a fill’s width is its thickness. An unsized vertical slider asks for 20 by 120.
use lurq::{components::Slider, core::Signal, node::SliderOrientation};
let level = Signal::new(60);
Slider::new(level) .range(0, 100) .orientation(SliderOrientation::Vertical) .height(160.0) .track(|style| style.width(4.0).background("#334155")) .fill(|style| style.background("#f97316")) .thumb(|style| style.size(14.0, 14.0).background("#f8fafc"));Slider::new_range(Signal<(i32, i32)>) and Slider::new_range_f32(Signal<(f32, f32)>) put two thumbs on one track, bound to a low value and a high one, with the fill between them. A press on the track moves the nearer thumb there (of two at one place, the one on the side of the press), a drag moves the thumb it began on to its end, and neither thumb passes the other: the low one stops at the high one’s value. Each thumb is a stop of Tab, the low one first going forward and the high one first going back, and the keys move the focused thumb, which alone takes the thumb_focused style. Both thumbs take the same thumb style. A range slider can be vertical too.
let price = lurq::core::Signal::new((20, 80));lurq::components::Slider::new_range(price).range(0, 100).step(5);Slider Keys
Section titled “Slider Keys”| Key | |
|---|---|
| Right, Up | One step toward the greatest value |
| Left, Down | One step toward the least |
| Page Up, Page Down | A tenth of the range, in whole steps and at least one step, as a browser’s range input pages |
| Home, End | To the least value, to the greatest |
The keys are the same for a vertical slider, and for the focused thumb of a range slider, which stops at the other thumb’s value. A disabled slider is not a stop of Tab and takes no key.
In a form a range slider submits two entries under its name, its low value and then its high one. SliderHandle::values() reads both values, value() the low one, and set_from_ratio moves the thumb nearer the ratio, as a press does.
Select
Section titled “Select”Select::new binds a Signal<T> for one value and Select::multiple a Signal<Vec<T>>. Options are (value, label) tuples or SelectOptions, which add a detail line under the label, an element before or after the label, and a disabled state:
use lurq::components::{Select, SelectOption};
Select::new(plan.clone()) .placeholder("Plan") .options([ SelectOption::new(Plan::Free, "Free"), SelectOption::new(Plan::Team, "Team"), SelectOption::new(Plan::Enterprise, "Enterprise") .detail("Contact sales to enable") .disabled(true), ])A disabled option cannot be chosen by pointer or keyboard, never takes the hover or keyboard highlight, and is skipped by arrow keys, Home/End and type-ahead.
leading(element) draws an element before the label and trailing(element) one after it, at the row’s end: a brand mark, a status dot, a badge. An option can have both:
SelectOption::new(Connection::Claude, "Claude Code") .detail("work account · Max") .leading(Svg::from_str(CLAUDE_MARK).width(16.0).height(16.0)) .trailing(Text::new("default"))- The element keeps its own size and sits
SelectStyle::option_adornment_gap(default 8) from the label. It is centred on the label’s line, also when the option has a detail line. - The closed field of a single-select shows the selected option’s elements around its label. A multi-select field shows none. A custom
Select::triggergets them asstate.leadingandstate.trailing. - A disabled option’s elements get the row’s disabled look (the default
option_disabledopacity). - The elements are decorative: type-ahead and automation keep using the label. Like a
SelectIcon::element, they are plain nodes: pass an icon, SVG, text or layout element, not a stateful component.
leading(element) draws the same element in every state. leading_with and trailing_with take a builder instead, called each time the row or the field is built, so a mark can follow the label’s look:
SelectOption::new(Connection::Codex, "Codex").leading_with(|state| { // The label's colour in this state, when the style sets one. let color = state.text_color.clone().unwrap_or(PaletteColor::Foreground.into()); mark(CODEX_MARK, color)})The builder receives a SelectAdornmentState: selected, highlighted (the keyboard highlight) and disabled for the option, in_field when the element is built for the closed field instead of a menu row, and text_color, the text_color of the row’s resolved part (option with its state parts merged, or the trigger part on the field; None when the part sets none). The pointer hover is not a state: as for the label, it repaints the row’s fill, border and shadow without rebuilding it.
group(label) starts a group of options at the option: the menu draws a separator above it, unless it is the first row, and the label over it, unless the label is empty; the options after it are in the group until another starts one. The separator and the label are rows of the menu, not options, so the keys, type-ahead and the pointer pass them by. hint(text) is a short note at the end of an option’s row, after its trailing element (“beta”, “soon”); the closed field does not show it:
Select::new(platform.clone()).options([ SelectOption::new(Platform::Windows, "Windows").group("Desktop"), SelectOption::new(Platform::Linux, "Linux"), SelectOption::new(Platform::Ios, "iOS").group("Mobile").hint("beta"),])SelectStyle::group_label(part) styles a group’s label row (padding, fill, text and color), separator(part) the line between groups (its background is the line’s color, its min_height the thickness, 1 unset, its padding the room around it), and option_hint(part) the hint’s text.
A pointer press on the trigger opens the menu without a highlight. On the focused select:
| Key | Closed | Open |
|---|---|---|
ArrowDown, ArrowUp (with or without Alt) | Open with the selected option highlighted, else the first enabled one | Move the highlight over enabled options, stopping at the ends. After a pointer open, the first arrow highlights the selected option, else the first enabled one |
Home, End | Highlight the first or last enabled option | |
Enter, Space | Open like the arrows | Choose the highlighted option: single-select closes, multi-select toggles it and stays open. With no highlight the menu closes without a change |
| Letters | Type-ahead: highlight the next enabled option whose label starts with the typed text. Repeating one letter cycles through its options; typing within a second extends the text, Space included | |
Escape, Tab | Close without a change |
The highlighted option scrolls into view, and opening scrolls the selected option into view. Focus stays on the select throughout. A press outside closes the menu without a change. By default that is all it does, like Escape: the select keeps focus, and the element under the pointer receives no press or click until the next press. A press on another dropdown’s trigger (another select, or the anchor of a dismissible popup) is the exception: it closes the menu and opens that dropdown in one press. Select::outside_press(OutsidePress::PassThrough) delivers the closing press as well; it then follows the usual press rule: it blurs the select, or focuses the pressed element if that can take focus. See Popups And Outside Presses.
A select is identified across re-renders by the signal it binds, like a TextInput: its open menu, keyboard highlight and focus stay with it when siblings are inserted, removed or reordered, and never pass to another select. Create the signal once (in create or as a field), not per render; a new signal each render is a new select, so its menu closes on every re-render. The highlight survives a re-render only while its row shows the same enabled option; when options are replaced it is cleared, so Enter closes without a change.
SelectStyle styles the trigger, the menu and the options with SelectPartStyles. Colours, border sizes, radii, spacing, typography and shadows accept theme roles.
SelectStyle::new() takes its colors from the theme, through the recipe the theme keeps for the engine’s select (engine_select, by the parts and states of ui::Select: SelectPart::Trigger, Panel, Item, Detail, Hint, Group, Separator, and SelectState::Open and Selected). The design’s is the trigger on Background in an edge of Border, Ring under the pointer, focused and open; the menu on Card; an option on Canvas under the pointer and on Primary while chosen; what is muted in MutedForeground. ThemeDefinition::legacy() gives the roles of 0.62. A theme restyles every engine select with theme.ui.patch::<SelectStyle>(..); the design system’s ui::Select has its own recipe. A style written out:
use lurq::{ app::theme::{PaletteColor, ShadowStyle, TypographyStyle}, node::{BoxShadow, SelectCheckmarkPosition, SelectIcon, SelectPartStyle, SelectStyle, padding::Padding},};
// "icon" is an app typography role that selects the icon font at 14 px.let icon = |glyph: &str| SelectIcon::glyph(glyph, TypographyStyle::extra("icon"));let ring = BoxShadow::new(0.0, 0.0, 0.0, PaletteColor::Ring).spread(1.0).inset();
SelectStyle::new() .trigger_open(SelectPartStyle::new().border_inside(1.0, PaletteColor::Ring)) .chevron(icon("\u{e06d}")) .chevron_open(icon("\u{e070}")) .chevron_color(PaletteColor::MutedForeground) .menu( SelectPartStyle::new() .background(PaletteColor::Card) .border_inside(1.0, PaletteColor::Border) .rounded(11.0) .padding(Padding::all(4.0)) .box_shadow(ShadowStyle::Lg), ) .max_menu_height(266.0) .option( SelectPartStyle::new() .min_height(32.0) .padding(Padding::symmetric(8.0, 0.0)) .rounded(7.0) .typography(TypographyStyle::Body), ) .option_hovered(SelectPartStyle::new().background(PaletteColor::Canvas)) .option_selected(SelectPartStyle::new()) .option_selected_hovered(SelectPartStyle::new().background(PaletteColor::Canvas)) .option_highlighted(SelectPartStyle::new().box_shadow(ring)) .option_disabled(SelectPartStyle::new().text_color(PaletteColor::MutedForeground)) .single_checkmark(true) .checkmark(icon("\u{e06c}")) .checkmark_size(14.0) .checkmark_position(SelectCheckmarkPosition::Trailing) .checkmark_color(PaletteColor::Primary)- An option row merges
option, thenoption_selected, the pointer hover (option_hovered), the keyboard highlight,option_selected_hovered, the highlighted-and-selected part, andoption_disabledlast. Withoutoption_highlighted, the keyboard highlight looks like the hover (option_hovered,option_selected_hovered). With it, the highlight has its own look, such as an inset ring from an insetbox_shadow, which composes with the hover fill;option_selected_highlightedthen styles a highlighted selected option. The pointer hover changes a row’s fill, border and shadow. SelectPartStylehasbackground, borders,rounded,padding,min_width,min_height,box_shadow,opacity(menu and options),outline(a ring the trigger paints over itself, at a negative offset inside its edge:trigger_focusedandtrigger_opencan be a focus ring), and text as atypographyrole, an explicittextstyle and atext_color. The defaultoption_disabledisopacity(0.45).option_detailstyles detail lines; the default isCaptioninTextMuted.trigger_gap(a number or a spacing role, default 8) is the room between the default trigger’s label and its chevron.- The menu opens below the trigger at the trigger’s width,
menu_gap(default 4) away, or above it when there is no room below.min_menu_width(260.0)lets a menu grow wider than a narrow trigger; it is still capped by the viewport width and repositioned to fit.menu_fits_options(true)makes it as wide as its longest option instead, with the room of a chosen option’s mark, for a trigger as wide as the one value it shows;min_menu_widthstill holds.max_menu_height(default 240) limits its height; the options scroll inside.menu_scrollbarreplaces the theme scrollbar; its insets are measured from the menu’s outer bounds, border included (see Scroll foredge_inset/end_inset). The menu’s padding insets the options and scrolls with them. - Option rows are at least 34 px tall unless the option part sets
min_height. The default option part pads labels by 10 px horizontally, like the trigger. - The chevron defaults to the glyph
▾atchevron_size(default 10) in the trigger’s text style.chevronreplaces it with aSelectIcon:SelectIcon::text(a glyph in the part’s explicit text style),SelectIcon::glyph(a glyph in a typography role, such as an icon font) orSelectIcon::element(an app-built element; the supplier receives the configured colour).chevron_openis drawn instead while the menu is open. - Multi-select marks chosen options with a checkmark.
single_checkmark(true)also shows it on a single-select’s selected option. It is off by default: a single-select marks its selection withoption_selectedonly. When checkmarks are shown before the label, or in a multi-select, every option reserves the checkmark slot (checkmark_size, default 16 wide), so labels do not shift; a single-select’s trailing checkmark takes its room on the selected row only, so the other rows’ labels and trailing elements run to the row’s end.checkmark_positionputs the slot before or after the label,checkmark_gap(default 6) separates them, andcheckmarkreplaces the✓glyph with aSelectIcon. Select::trigger(|state| ...)replaces the trigger content. It receives the label, placeholder and selection, and a single-select’s selected option’sleadingandtrailingelements.- The trigger’s fill is its part’s
background: the theme’sBackgroundin the defaultSelectStyle(SurfaceInputunderThemeDefinition::legacy()). A trigger part without abackground, as inSelectStyle::unstyled()or a part passed to.trigger(...)that sets none, paints no fill, like a button or text input without a background, so an app that styles the trigger itself (or puts it on a surface of its own) sees that surface. Its border, radius and shadows still paint.Tree::painted_quads()shows the fill in tests (see Testing).
Programmatic Interaction
Section titled “Programmatic Interaction”Nodes tagged with .id("...") can be driven imperatively from integration code and tests, browser-DOM style. Look the node up on Tree and use the handle’s universal actions or a typed downcast:
Column::new() .child(TextInput::new(email.clone()).id("email")) .child(Checkbox::new(agree.clone()).id("agree")) .child(Button::new("Save").id("save").on_click(on_save))// DOM el.click(): fires the node's own on_click at its bounds center// without hit-testing, focuses focusable nodes, submits for submit buttons.tree.get_element_by_id_mut("save").unwrap().click();
// DOM el.value = x: writes the backing signal and clamps the caret,// but does NOT fire on_input handlers.tree.get_element_by_id_mut("email").unwrap() .as_text_input().unwrap() .set_value("ada@example.com");
// Widget default actions live on the typed handles.tree.get_element_by_id_mut("agree").unwrap().as_checkbox().unwrap().toggle();focus() and blur() route through the tree’s focus machinery and fire the node’s own on_focus/on_blur handlers. Typed handles exist for TextInput, Checkbox, Slider, and Select; downcasting a different node kind returns None.
These operations write signal-backed widget state, so they behave like real user input from the app’s perspective — minus the event side effects called out above. For pointer-fidelity interaction (hover, capture, hit testing), drive tree.mouse_down / tree.mouse_up instead, composing coordinates from the handle’s bounds().center(). See Runtime And Retained Tree for the lookup and mutation contract.
Drag And Drop
Section titled “Drag And Drop”Use high-level DnD components when you want draggable nodes and drop zones.
use lurq::components::{ DragContainer, DragContainerProps, Draggable, DraggableProps, DropZone, DropZoneProps, Rect, Stack,};
let card = Draggable::mount( ctx, DraggableProps::new().on_drag_end(|event| { println!("drop result: {:?}", event.drop_result); }), Rect::new(64.0, 64.0) .background("#2563eb") .absolute_position(24.0, 24.0),);
let zone = DropZone::mount( ctx, DropZoneProps::new().on_drop(|event| { println!("source {:?} dropped on {:?}", event.source_id, event.target_id); }), Rect::new(160.0, 100.0) .background("#16a34a33") .absolute_position(180.0, 80.0),);
DragContainer::mount( ctx, DragContainerProps::new(), Stack::new() .size(420.0, 240.0) .child(zone) .child(card),)DragContainerProps::new() bounds descendant draggables to the container surface. Use DragBounds::None when the draggable should not be constrained.
Low-level node drag handlers are also available: .on_drag_start, .on_drag_move, .on_drag_end, and .on_drop.
A Drag Holds The Pointer
Section titled “A Drag Holds The Pointer”A press on an element with on_drag_* handlers starts a drag that holds the pointer until the button is let go, as a pointer capture does in a browser:
- Every move reaches
on_drag_move, wherever the pointer is: over other elements, and out of the window too, where the shell goes on passing the moves of a held button.DragEvent::total_delta_xandtotal_delta_ycount from where the press was, andDragEvent::outside_windowsays the pointer is out of the window, past any of its edges (where a tab let go is taken out into a window of its own). - Nothing is hovered meanwhile and no text is selected by the move.
- The window shows the cursor that was under the pointer at the press for the whole drag (
Tree::cursor), over elements with cursors of their own and out of the window, until the release; then it is that of what is under the pointer again. - A drag that moved clicks nothing when it is let go.
.start_drag_buttons(MouseButtonMask::LEFT)keeps the other buttons from starting one.
A divider that resizes what is beside it needs nothing more than its handlers and its cursor:
use lurq::{ app::events::{DragEvent, MouseButtonMask}, components::Row, node::CursorIcon,};
Row::new() .width(6.0) .cursor(CursorIcon::ColResize) // shown for the whole drag, whatever the pointer crosses .start_drag_buttons(MouseButtonMask::LEFT) .on_drag_move(move |event: DragEvent| resize_by(event.total_delta_x)) .on_drag_end(move |_: DragEvent| save_layout());ui::Splitter is such a divider between panes, with the keys, panes that close and a layout the app saves.
A Drag That Scrolls Its Container
Section titled “A Drag That Scrolls Its Container”.drag_autoscroll(true) on an element with on_drag_* handlers makes its drag scroll the scroll container it is in: the nearest one around it that has content beyond its viewport. While the pointer of the drag is within about 12 logical pixels of an edge of that container, or past the edge, the content scrolls toward the pointer on the axes the container scrolls, faster the further the pointer goes, a step each frame for as long as the pointer is held there; it stops at the end of the content and when the drag ends. It is off by default.
After each step the drag’s on_drag_move handlers are called with the pointer where it is, though it has not moved: what follows the drag reckons again with what scrolled under it. The container’s on_scroll handlers hear each step, as they hear the wheel.
use lurq::{ app::events::{DragEvent, MouseButtonMask}, components::{Column, ScrollVertical},};
// A rectangle dragged down a long list: at the list's bottom edge the list scrolls, and each step moves the// rectangle's end with it.ScrollVertical::new( Column::new() .start_drag_buttons(MouseButtonMask::LEFT) .drag_autoscroll(true) .on_drag_move(move |event: DragEvent| extend_to(event.x, event.y + state.scroll_y())),).with_scroll_state(state.clone());ui::SelectionMarquee is such a drag over a surface.
File Drag And Drop
Section titled “File Drag And Drop”Files dragged into the window from the OS (Explorer, Finder, another program) reach the element under the pointer, with the window’s overlays and modals hit-tested as for the mouse, so a drag over a popup reaches the popup:
use lurq::{app::events::{FileDragEvent, FileDropEvent}, components::Column};
Column::new() .background("#1f2937") .drag_over(|style| style.background("#1e3a8a").border_inside(1.0, "#60a5fa".into())) .on_file_drag_enter(|event: FileDragEvent| { if event.paths.has_folders() { event.refuse(); // folders are not attachments } }) .on_file_drop(move |event: FileDropEvent| { for path in event.paths.files() { attachments.update(|list| list.push(Attachment::file(path.to_path_buf()))); } })on_file_drag_enter(FileDragEvent)fires once when the drag comes over the element,on_file_drag_over(FileDragEvent)on every move over it (withx,yin logical pixels, as on aMouseEvent),on_file_drag_leave()when it moves off the element or leaves the window without a drop, andon_file_drop(FileDropEvent)on the drop. Enter, over and drop bubble from the element under the pointer to the root;stop_propagation()ends that.event.pathsis aDraggedPaths, given once for the whole drag however many files it holds:paths(),files(),folders(),has_folders()anditems()(each aDroppedPathwithis_folder(), looked up once withPath::is_diron the shell’s thread when the drag enters; a path on a slow network drive makes that look-up slow). Only files and folders arrive: text or an image dragged from a browser is ignored, since winit reports nothing for it.- While the drag is over an element, its
.drag_over(...)style applies, likehoveredunder the pointer, andInteractionState::is_drag_over()reports it.event.refuse()(orprevent_default()) on an enter or over event refuses the drag at the element whose handler called it (not at its ancestors or siblings) for as long as the drag stays over that element: no element shows the style andTree::file_drag_accepted()reportsSome(false)while it does; the drag leaving the element and entering it again asks again. The OS cursor is not changed by a refusal: winit answers the OS with a copy effect before lurq sees the drag, on Windows and macOS alike. The drop is still delivered toon_file_drop, whose handler ignores what it refused (the folders in the example). - A drop ends the drag: the
drag_overstyle goes without anon_file_drag_leave.
The winit shell collects the OS’s burst of one event per file into one session on Windows and macOS, and reads the pointer position from the OS while the drag hovers (the OS owns the pointer during a drag, so no CursorMoved arrives), every 16 ms, delivering on_file_drag_over when it moved. A hover ends as a leave when no mouse button has been pressed for 250 ms of polls (the OS drag ended without winit telling; read from the OS on Windows and macOS — the grace period covers the release, which the OS reports before its drop callback runs, so a drop within it continues the same session without a leave, and it covers drags whose button state is reported differently, a touch or pen drag promoted to a mouse drag, ClickLock, macOS drag lock, which end after the grace period at most and have not been checked), or when it neither moved nor got a drop or a cancel for 60 s, since its source is gone (a program that died mid-drag) and polling would never stop; a drag held still that long is ended too, and a drop that comes later still arrives. On Linux the last pointer position the window saw is used. A shell that drives a Tree itself calls Tree::file_drag_enter(paths, x, y), file_drag_over(x, y), file_drag_leave() and file_drop(paths, x, y) with physical pixels.
Files a person gives
Section titled “Files a person gives”lurq::files gives a file dropped and a file chosen as one type, so an app handles both alike. DroppedFile::from_path(path) is a file of a drop (its name, its size read once, its path); DroppedFile::new(name, size) is one with no path, as a browser gives. file.extension(), file.kind() (FileKind::Image, Video, Audio, Text, Archive, Other, by the extension) and file.is_accepted(&["image/*", "pdf"]) judge it; format_size(bytes) says a size as 4 KB or 1.2 MB.
FileDialog opens the system’s dialog for files to open. It runs off the loop, and its future does not borrow the window, so it is what a ctx.future_action runs:
use lurq::files::FileDialog;
// In `create`.let window = ctx.window();let choose = ctx.future_action(move |()| { FileDialog::new().title("Add images").filter("Images", &["png", "jpg"]).multiple(true).pick_result(&window)});// In a handler: `choose.run(())`; `choose.state()` then holds the chosen `Vec<DroppedFile>`, empty when the// person cancelled.| Platform | A drop | The dialog |
|---|---|---|
| Windows | Paths, from Explorer | The system’s (rfd, with the feature file_dialog): paths and sizes. It is modal to the window it is opened over: the window takes no input until it closes |
| macOS, Linux | Paths, from Finder or a file manager | The system’s: paths and sizes. It has no parent window yet, so it is not modal to the app’s: a press of the window behind it puts the dialog behind the window |
| A browser | None: winit reports no drop from the system | The browser’s file input, which a press must open: names and sizes, no path. Its bytes are not read through lurq yet |
| iOS | None | lurq’s own, with no feature: a menu of where the files come from (the photo library, the camera, Files), then the system’s photo picker, a camera or the document picker. Files are given as copies in the app’s temporary folder, with their paths |
On a phone a dialog of files asks first where they come from, as Safari’s file input does. sources says which it offers (FileSource::Files, PhotoLibrary, Camera), of those the device has; one alone opens at once. Its words are the locale’s (Locale::fields, Locale::common):
use lurq::files::{FileDialog, FileSource};
FileDialog::new().sources([FileSource::Camera, FileSource::PhotoLibrary]).multiple(true).pick_result(&window)The camera is offered where the device has one and the app’s Info.plist says why it uses it (NSCameraUsageDescription); without the words iOS would end the app, so lurq leaves the camera out and says once in the log what to add. A dialog of one file opens the system’s camera, with its review (“Use Photo”). A dialog of several opens lurq’s own, as a messenger’s is: it stays open between photos, with the lenses the phone has (0.5×, 1×, 2×), a pinch to zoom, a tap to focus, the flash (auto, on, off) and the other camera; the photos taken are beside the shutter, and a tap opens them in a viewer as a gallery’s (swiped, zoomed, one taken out); Done gives them all, Cancel none. Each photo is a JPEG in the temporary folder. Where the person has not let the app use the camera, the system’s camera is shown, which says so. On a desktop, which has no camera, sources chooses the photo library where it is the one source: Photos on macOS, the user’s Pictures on Windows.
The same dialog chooses a folder and where a file is to be saved, each given as its path, or None when the person cancelled:
// In a component's `create`: a folder, and a place to save a file.let window = ctx.window();let folder = ctx.future_action(move |()| { let chosen = FileDialog::new().title("Project folder").pick_folder(&window); async move { Ok::<_, ()>(chosen.await) }});let window = ctx.window();let save = ctx.future_action(move |()| { let chosen = FileDialog::new().filter("Markdown", &["md"]).file_name("report.md").pick_save(&window); async move { Ok::<_, ()>(chosen.await) }});pick_folder takes the dialog’s title and the folder it opens in; pick_save its filters too, as the kinds the file can be saved as, and the file_name it starts with. The system asks before a file that is there is chosen, and lurq writes nothing. A browser has neither dialog (a page is given no path), and gives None. On iOS the folder is the folder itself, which the app may read and write while it runs; where to save is chosen after an empty file of the name is made, which the person puts where they choose (Files, iCloud Drive, the phone), and its path there is given. ui::PathField is made of these.
Without the feature file_dialog, pick gives nothing and says so once through tracing. Under an MCP server with a FileDialogBroker registered, pick asks the broker and no system dialog opens: an agent answers it. ui::DropZone and ui::FileUpload are made of these.