Design System
Design System
Section titled “Design System”lurq::ui holds the design system’s components and what a theme styles them with. It is being built a component at a time: this page describes what is in the crate today. The gallery (cargo run -p gallery) shows each component live.
use lurq::{components::Row, ui::{Button, ButtonVariant}};
Row::new() .spacing(8.0) .child(Button::new("Cancel").variant(ButtonVariant::Outline)) .child(Button::new("Save").on_click(|_| save()))A component is a builder that goes where an element goes. It takes the theme of the component being rendered around it, so nothing is passed to it, and what renders it renders again when the theme changes.
The Three Layers
Section titled “The Three Layers”| Layer | What it says | Where it is set |
|---|---|---|
| Tokens | What blue is, how round Md is | The palette and the scales of the theme |
| Recipes | How each part of a component looks in each case | theme.patch_recipe::<Button>(...), theme.set_recipe::<Button>(...) |
| Renderers | What nodes a component is built from | theme.set_renderer::<Button>(...), theme.set_part_renderer::<Button, _>(...) |
Each has the design as its default. Most apps change tokens only. A brand changes recipes. A look whose controls are built differently changes renderers.
The gallery shows each level live: its Styling page (Getting started › Styling, cargo run -p gallery -- --route /styling) changes a palette role, patches a recipe, styles one instance with .style, .rules, .state and .force, and gives a part a renderer of its own, each with its code and in the order they are laid. Every component’s playground has a Styling tab beside its props: the parts and the states the component declares, a part restyled live for the one on the stage (.style(Part, ..)) or for every one in the stage’s own theme (theme.patch_recipe::<X>(..)), and the Rust of both.
Recipes
Section titled “Recipes”A component is made of named parts: a button has Root, Label, Leading and Trailing. A recipe is a list of rules, and a rule says that in a case a part has a style:
use lurq::{ app::theme::{ControlSize, PaletteColor, RadiusSize}, ui::{ButtonPart, ButtonVariant, Recipe, Selector},};
let recipe = Recipe::new() // Always. .base(ButtonPart::Root, |s| s.height(ControlSize::Md).padding_x(16.0).radius(RadiusSize::Md)) // For a variant. .variant(ButtonVariant::Primary, ButtonPart::Root, |s| { s.background(PaletteColor::Primary).foreground(PaletteColor::PrimaryForeground) }) // For a variant under the pointer. .when(Selector::new().variant(ButtonVariant::Primary).hovered(), ButtonPart::Root, |s| { s.background(PaletteColor::PrimaryHover) });| Rule | Holds |
|---|---|
base(part, style) | Always |
variant(variant, part, style) | For a variant |
size(size, part, style) | For a size |
density(density, part, style) | While the theme is at a density |
row_density(selector, part, height), by_density(selector, part, style) | At each density but the default, by the step a row moves at it (ROW_STEPS): a row height high at the default, or a style given the step |
at(breakpoint, part, style) | In a window at a breakpoint or wider |
state(state, part, style) | While the component is in a state: disabled, checked, loading |
hovered(part, style), pressed(...), focus_visible(...) | Under the pointer, held down, focused from the keyboard |
within(part, style) | While the interaction group the part is in is under the pointer or holds the focus: what a row shows only then |
when(selector, part, style) | In the case a Selector describes: several of the above together |
- The rules that hold are laid one over another, the more specific over the less: always, then a variant, then a size, then a density, then a breakpoint (a wider one over a narrower), then states (more of them over fewer). Rules of one rank apply in the order they were written.
- A style a later rule sets replaces the earlier one’s field by field; what it leaves alone shows through.
- Variants, sizes, states and parts are names. A component gives its own as enums, which are accepted where a name is, and an app adds any others:
.variant("brand", ...),.state("pinned", ...). - Rules for the pointer and the keyboard become state styles of the node. A hover renders nothing again, and changes only what is painted: no size, padding or text.
Recipe::extend(&other)adds another recipe’s rules after this one’s.
A part that shows only while the element it is in is pointed at or focused, as the action at the end of a tree’s row,
is styled within: the component makes that element an interaction group (.interaction_group(true)), and the rule
becomes the part’s within_style. A part in no group answers to the button it is in: a within_hovered rule of a
button’s label paints it while the button is under the pointer. Selector::within() joins it with a variant or a state, PartStyles::within is what
the rules gave it, and a part drawn with a forced interaction shows it too.
use lurq::{ app::theme::Density, ui::{Recipe, TreeViewPart},};
// Hidden at rest, shown in its row's light, and always under a finger, which points at nothing.let rules = Recipe::new() .base(TreeViewPart::Reveal, |s| s.opacity(0.0)) .within(TreeViewPart::Reveal, |s| s.opacity(1.0)) .density(Density::Touch, TreeViewPart::Reveal, |s| s.opacity(1.0));Breakpoints
Section titled “Breakpoints”A rule at(Breakpoint::Md, ...) holds at that breakpoint and at every wider one; a rule with no breakpoint is for every width, the narrowest included. This is the order Responsive values resolve in.
use lurq::{app::theme::Breakpoint, ui::{Button, ButtonPart}};
// A taller button on a narrow window, the design's from the medium breakpoint up.theme.patch_recipe::<Button>(|rules| { rules .base(ButtonPart::Root, |s| s.height(48.0)) .at(Breakpoint::Md, ButtonPart::Root, |s| s.height(36.0))});A component is built again when the window’s width crosses a breakpoint, not at every resize. ui::current_breakpoint() is the breakpoint of the window what is being built is in.
Density
Section titled “Density”A theme is at one density, and a rule density(Density::Compact, ...) holds while it is at that one. A component is resolved at the density of the theme it is built in, and is built again when theme.set_density(..) changes it.
use lurq::{app::theme::Density, ui::{Button, ButtonPart}};
// A theme whose buttons are as high as a row is: lower in a compact tool, higher under a finger.theme.patch_recipe::<Button>(|rules| { rules .density(Density::Compact, ButtonPart::Root, |s| s.height(Density::Compact)) .density(Density::Touch, ButtonPart::Root, |s| s.height(Density::Touch))});theme.set_density(Density::Compact);The design’s recipe for Button has no rule for a density: a button has its sizes, and so have the other controls (an input, a select’s box). The design’s rows have: an item of a menu, a sidebar or a command palette, an option of a select, a combobox or a multi select, a row of a tree view, a tab, an accordion’s header. A row moves from its height at the default by ROW_STEPS, 8 lower at compact and 8 and 12 higher at comfortable and touch, as a row of 36 is 28, 44 and 48; a row the design draws 32 high is 24, 40 and 44. Recipe::row_density(selector, part, height) writes those rules for a part of height at the default in the case of selector, and by_density(selector, part, |style, step| ..) any other: an accordion’s header moves its padding. Selector::density(..) joins a density with a variant, a size or a state in one rule.
The Touch Form
Section titled “The Touch Form”Some components have a form dressed for a finger: the lightbox’s phone viewer, the picture’s phone form, the video player’s touch form. Which one they take is the person’s pointer and nothing else: under a finger (Pointer::Coarse) the finger’s, under a mouse, a trackpad or a pen (Pointer::Fine) the pointer’s. ui::touch_form() says it for what is being built, and is what each of them reads; an app’s own component with a touch form reads it too. The pointer starts as the platform says (Coarse on iOS and Android, Fine on a desktop, in the browser what (pointer: coarse) says) and follows the last input unless the app pins it: see A Finger Or A Mouse. A component’s own prop for its form (variant(..), touch(bool)) wins over it.
Neither the window’s width nor the theme’s density is asked. A narrow window of a desktop is a narrow room, and a component lays itself out in it (labels to an ellipsis, a row into a column, the lightbox’s level giving way), but it keeps the pointer’s form: a phone’s chrome in a narrow desktop window would take away the buttons a mouse needs. A density is how large rows are, at any pointer. A rule for a breakpoint changes the layout, never the form. A lightbox that is open keeps the form it opened in until it closes, so the finger that lands on it does not change it under itself; the app setting the pointer reaches it at once.
use lurq::{app::Pointer, ui::{Lightbox, LightboxVariant}};
// A kiosk with a touch screen: every component takes its touch form.app.set_pointer(Pointer::Coarse);
// One lightbox in the phone's viewer whatever the pointer.Lightbox::new(open, pictures).variant(LightboxVariant::Phone);
// An app's own component.let swipes = lurq::ui::touch_form();Part Styles
Section titled “Part Styles”PartStyle is the style of one part: a patch in which every field is optional. Every component uses this one type.
| Builder | Sets |
|---|---|
background(color), foreground(color) | The fill, and the color of the text and icons in the part and under it |
border(border), radius(radius) | A border on every side; the corners |
underline(border) | A line along the bottom of the part only: what a link has under the pointer |
start_line(border) | A line along the start side of the part only: what marks the selected tab of a list that runs down the side |
shadow(shadow), veil(color) | Shadows; a color laid over the fill and under the content (StateHover, StatePressed) |
outline(outline), focus_ring() | An outline; the theme’s focus ring as the outline |
opacity(value) | A number, or a level of the theme’s (OpacityLevel::Disabled) |
padding_x(spacing), padding_y(spacing), gap(spacing) | Padding across and down, and the room between the part’s children |
padding_top(spacing), padding_bottom(spacing), padding_start(spacing), padding_end(spacing) | The padding of one side, laid over padding_y or padding_x: 6 above and 4 under a label. Start is the left, end the right. paddings() reads the four as they come out: top, end, bottom, start |
width(length), height(length), min_width(length), min_height(length), max_width(length), square(length) | A Length: pixels, a step of the control, density or icon scale, Length::Fill. max_width is the most the part grows to |
typography(role) | Every field of the part’s text at once |
font_family(family), font_size(px), weight(weight), font_style(style), line_height(ratio), letter_spacing(px) | One field of the text, over the role’s |
transition(PartTransition::new(Transition::background_color(), MotionDuration::Fast)) | A transition, with a duration and an easing of the theme’s |
enter(PartAnimation::new(FADE_IN, MotionDuration::Base, MotionEasing::Enter)), exit(PartAnimation::new(FADE_OUT, ..)) | Keyframes the part plays as it appears and as it leaves, with a duration and an easing of the theme’s. A part that leaves is kept while it plays where what holds it keeps leaving parts: an overlay’s layer, or a child with an id or a key of an element with presence(). ui::FADE_IN and ui::FADE_OUT are an opacity from nothing to whole and back, which every window has |
cursor(icon) | The cursor over the part |
Colors, radii, spacings and shadows are roles of the theme or concrete values, as everywhere in lurq.
A part’s foreground is the color of its text over what its typography role says: where a theme’s role names a color (its TextStyle::color is not the default), a part that sets a foreground, at rest or in any of its states, still draws its text in that foreground, and a part that sets one only in a state draws its text in the role’s color at rest. Where the part sets no foreground, the role’s color stands, and a role that names none takes the foreground of what the text is in.
A part’s text is in one of the theme’s two families or in one by name:
use lurq::ui::{ButtonPart, FontFamily};
rules .base(ButtonPart::Label, |s| s.font_family("Georgia")) .variant("code", ButtonPart::Label, |s| s.font_family(FontFamily::Mono))What A Theme Changes
Section titled “What A Theme Changes”use lurq::{app::theme::RadiusSize, ui::{Button, ButtonPart, ButtonVariant}};
// Every primary button is a pill.app.theme().patch_recipe::<Button>(|rules| { rules.variant(ButtonVariant::Primary, ButtonPart::Root, |s| s.radius(RadiusSize::Full))});theme.patch_recipe::<C>(|rules| ...) | Lays rules over the component’s recipe. What it adds wins where both style a case. |
theme.set_recipe::<C>(recipe) | Gives the component a recipe in place of the design’s: nothing of the design’s is left under it. |
theme.set_renderer::<C>(renderer) | Builds other nodes for the same behavior. |
theme.set_part_renderer::<C, R>(part, renderer) | Builds one part; the rest is still built by the renderer it had. |
The same is on a ThemeDefinition, in its ui field: definition.ui.patch::<Button>(...), set_recipe, set_renderer, set_part_renderer, reset_recipe.
What a theme resolved for a component in a case it keeps until the theme changes, so a list of a thousand buttons resolves the recipe once.
A Bare Theme
Section titled “A Bare Theme”ThemeDefinition::bare() has the design’s tokens and no recipe. Every part of every component comes out unstyled, and every component still works: a bare button is its label, pressed by a click and by the keyboard. It is the base for a look that shares nothing with the design’s.
use lurq::{ app::theme::{RadiusSize, ThemeDefinition}, node::color::Color, ui::{Button, ButtonPart, Recipe},};
let mut look = ThemeDefinition::bare();look.ui.set_recipe::<Button>( Recipe::new() .base(ButtonPart::Root, |s| { s.height(44.0) .padding_x(24.0) .radius(RadiusSize::Full) .background(Color::from_hex("#111827")) .foreground(Color::from_hex("#f9fafb")) }) .hovered(ButtonPart::Root, |s| s.background(Color::from_hex("#374151"))),);app.theme().apply(look);Renderers
Section titled “Renderers”A recipe restyles a component and cannot change what it is made of. A renderer builds its nodes. It is given the component’s view: what the component was given, the style of each of its parts, and its behavior ready to be dressed.
use std::sync::Arc;use lurq::{components::{Column, Rect}, ui::{Button, ButtonPart, ButtonRenderer, ButtonView}};
// A button whose label is in capitals with a bar under it.let renderer: ButtonRenderer = Arc::new(|view: ButtonView| { let label = view.part(ButtonPart::Label).text(&view.label.to_uppercase()); view.root().child(Column::new().child(label).child(Rect::new(20.0, 2.0))).into()});app.theme().set_renderer::<Button>(renderer);view.root()is the element that is pressed, focused and disabled, with the style of the root part and nothing in it yet. The behavior is lurq’s: a renderer cannot leave it out.view.part(part)is the style of a part;.part(&style)on any element gives the element that style, andstyle.text("...")is a text in the part’s typography.- A renderer for one part leaves the rest to the renderer the component had:
use lurq::ui::ButtonPartRenderer;
let label: ButtonPartRenderer = Arc::new(|view| view.part(ButtonPart::Label).text(&format!("» {}", view.label)).into());app.theme().set_part_renderer::<Button, ButtonPartRenderer>(ButtonPart::Label, label);One Instance, One Place, One Subtree
Section titled “One Instance, One Place, One Subtree”// One instance, over what the theme gives it.Button::new("Wide").style(ButtonPart::Root, |s| s.padding_x(40.0));
// The buttons in the places of a component: what a message box says of its confirm button.let confirm = Recipe::new().base(ButtonPart::Label, |s| s.font_family("Georgia"));Button::new("Confirm").rules(&confirm);
// A subtree in a theme of its own: a dense inspector in a window that is not.let inspector = ctx.in_theme(&dense, |ctx| inspector_panel(ctx));
// An element and what is in it painted with another theme: a dark side bar in a light window.Column::new().theme(&dark).background(PaletteColor::Background).child(nav);- The order, later over earlier: the theme’s recipe, the rules of the place (
.rules(...)), the instance’s own (.style(...)). - Every builder of
lurq::uiisStyled: a trait withrules,stateandstyle, so what styles any component (a helper of the app’s over several kinds, the gallery’s playground) is written once:fn pill<C: Styled>(c: C, part: impl Into<Name>) -> C { Styled::style(c, part, |s| s.radius(RadiusSize::Full)) }. Styled::describe(name, value)says a state of any component to tooling that reads the tree, the DevTools and the MCP tree, as an element’s owndescribedoes:Callout::new(..).describe("tone", "warning"),Progress::new(0.4).describe("share", "40"). It is said on the node of the component’s root part, where its id is, when the renderer gives that node the part’s style, so a theme’s renderer says it too; it comes before what the component says of itself there (itsa11y_role, itsa11y_name), and a reader that takes the first value of a name takes the app’s. The instance’sRecipecarries it (Recipe::describe), laid as itsrulesare. Like an element’sdescribe, it says nothing unless a tooling feature (devtools,mcp) is on.ctx.in_theme(&theme, |ctx| ...)is the theme of everything the closure builds and mounts, and returns it as anElement. Components mounted in it keep the theme when they render again on their own, the one the closure returns as its root too (ctx.in_theme(&theme, |ctx| ctx.mount::<Panel>(props))): what it paints is in the theme after a render of its own as at its first.- The theme reaches the whole of the subtree. A component built in it takes its recipe and its renderers, the sizes, type, opacity and motion of its parts, its density and its icons from that theme; and the roles left on the nodes, a color of the palette, a radius, a border width, a shadow, a spacing role, a typography style, the scroll bar and the caret, are laid out and painted with that theme’s values. A subtree in a dark theme inside a light window is dark.
.theme(&theme)on any element does the second half alone: the element and what is in it are laid out and painted with the values of that theme. What was built outsidein_themekeeps the recipes it was built with, so this is for plain elements, andin_themeis for components.- A change of the subtree’s theme while the app runs lays the window out again, as a change of the window’s theme does, and is there at once: a transition in the subtree runs between the colors of its theme, and not from the window’s to its.
- What is declared in the subtree and drawn over the window, the content of a
Popup, aModal, the menu of aSelect, is laid out and painted with the subtree’s theme too. ui::current_theme()is the theme of what is being built. Outside a render there is none, and it is a neutral one that follows nothing: build components where they are rendered.
Ids Of Parts
Section titled “Ids Of Parts”A component given an id keeps it on its root, and names the node of each of its other parts after it: x- and the part’s name as its *Part enum writes it in a recipe, underscores and all. What finds a node by id (Tree::get_element_by_id, a test, DevTools, an agent over MCP) reaches a badge’s label or a progress’s fill with no id written for it.
use lurq::ui::{Badge, Button, DataList};
// status, status-dot, status-labelBadge::new("Online").dot(true).id("status");// about, about-term, about-value, about-term-2, about-value-2DataList::new().text("Version", "0.63.0").text("License", "MIT").id("about");// save, and its spinner save-spinner, the spinner's indicator save-spinner-indicatorButton::new("Saving…").loading(true).id("save");- A part of which there are several is told apart by its key where it has one: a day of a calendar by its date (
due-calendar-day-2026-11-20), a weekday by its English short name (x-weekday-mon, the same in every locale), the buttons of a calendar’s sidesx-nav-previousandx-nav-next, an item, an option, a tab or a segment by its key or value. Where it has none, by the order it is built in:x-term,x-term-2,x-term-3. - A node that has an id keeps it. An item the app gave an id
yisy, and names its own parts after it (y-label,y-chevron), whether the component has an id or not. - A component built inside another and given no id of its own is named after what it stands for there, and names its own parts after that: the spinner of a button
save-spinner, the calendar of a date pickerduedue-calendar(not after the panel it stands in), a dialog’s close buttonx-close. - A component given no id gives its parts none, and the ids are the same at every render of the same content, so a node keeps its state from one to the next.
- A renderer of a theme gets the same: what it gives
.part(&view.part(..))is named,view.recipe.part_id(part)is the id of the next node of a part for an element built otherwise, andstyle.keyed(key)names one by its key.
A glyph of the theme’s set, by name.
use lurq::{ app::theme::{IconSize, PaletteColor}, ui::{Icon, icons},};
Icon::new(icons::SEARCH); // 16 high, in the foreground of what it is inIcon::new(icons::SETTINGS).size(IconSize::Lg); // a step of the theme's icon sizesIcon::new(icons::CHECK).color(PaletteColor::Success); // a color of its ownIcon::new(icons::SPINNER).spin(true); // a spinnerIcon::new(icons::SPINNER).spin(true).spin_motion(SpinMotion::stepped(24)); // in 24 poses a second| Builder | |
|---|---|
Icon::new(name) | A constant of ui::icons, or a name the theme added |
size(size) | An IconSize (Md, 16, by default) or a number of logical pixels. The icon is a square of that side |
color(color) | A color in place of the foreground of what it is in |
spin(bool) | It turns once in ui::SPIN_PERIOD, a second |
spin_motion(SpinMotion) | How it turns, in place of the theme’s: in steps, and still where motion is reduced |
id(id), key(key) | Its id and key |
- An icon names no color: it is drawn in the
.foreground(..)of what it is in, as text is, so the icon of a button is the color of its label. ui::iconshas a constant for each of the 171 icons of lurq’s font (icons::CHEVRON_DOWNis"chevron-down"),icons::ALLlists them with their characters, andicons::FAMILYis the family of the font. Every app has the font loaded, hinted: at 16 and 20 pixels its strokes land on whole pixels of the display.- The theme says what a name is drawn with (
ThemeIcons). A theme gives a name another glyph, or adds names of its own, from a font the app loads; lurq’s components name the icons they draw, so they change with it. - A name the theme has no glyph for takes its room and draws nothing.
- A name the theme draws with an SVG (
IconSvg,theme.set_icon_svg(name, IconSvg::stroked(svg))) is that SVG at the icon’s size: a stroked one’s lines and a filled one’s shapes in the icon’s color (itscolor, or the foreground of what it is in), a colored one in its own colors, a brand’s mark. It turns where it spins. SVG is drawn with the featurecanvas; without it, or where the source is no SVG, it takes its room and draws nothing. - Most icons are lines.
icons::STAR_FILLis a solid star, the shape a rating lights: a glyph that is filled whereicons::STARis drawn. - Spinning icons are in phase: spinners that appear at different moments turn together.
ui::SPINis the keyframes of the turn, registered in every window; keyframe identifiers from0xFF00up are lurq’s own.
Spin Motion
Section titled “Spin Motion”How a spinning icon and a spinner (its ring, its dots, its bars) move: a SpinMotion.
use lurq::ui::{Icon, SpinMotion, Spinner, SpinnerKind, icons};
// 24 poses a second and none between, and still where the system asks for reduced motion.let motion = SpinMotion::stepped(24).still_when_reduced(true);Icon::new(icons::SPINNER).spin(true).spin_motion(motion);Spinner::new().kind(SpinnerKind::Dots).motion(motion);
// Every spinner that is not told its own, the ring of a loading button too.app.theme().set_spin_motion(motion);SpinMotion::SMOOTH, the default, moves at every frame the display has, so the window draws every frame while a spinner is shown.SpinMotion::stepped(per_second)holds each pose until the next,per_secondof them a second, and asks for no frame between: a ring of 24 turns 15 degrees at each of 24 steps of its second, and the window draws 24 frames a second whatever the number of spinners, for they all move on one clock. A period that is no whole number of steps is taken in the nearest number of them (the dots’ 1.2 seconds are 28 steps at 24, 14 there and 14 back), and the dots and the bars start on a step, so that all of them change at the same moment..still_when_reduced(true)leaves them in their pose at rest where motion is reduced (Theme::reduced_motion): the ring unturned, the dots and the bars as the design draws them still. Unless told so, a spinner moves under reduced motion too: one that stood still would say nothing, where nothing else says that something is under way.Theme::set_spin_motion(motion)(andUiDefinition::set_spin_motion) is the motion of every spinning icon and spinner given none of its own;Icon::spin_motionandSpinner::motionare one’s own.
use lurq::{app::theme::IconGlyph, ui::{Icon, icons}};
// The app loads its font, and the theme draws from it.app.load_font(include_bytes!("brand-icons.ttf").to_vec());theme.set_icon(icons::SEARCH, IconGlyph::new("brand icons", '\u{F002}'));theme.set_icon("rocket", IconGlyph::new("brand icons", '\u{F135}'));Icon::new("rocket");Button
Section titled “Button”An action a press starts: a click, or Enter or Space while it is focused.
use lurq::ui::{Button, ButtonShape, ButtonSize, ButtonVariant, icons};
Button::new("Delete") .variant(ButtonVariant::Destructive) .size(ButtonSize::Sm) .icon(icons::TRASH) .on_click(|_| delete());
// An icon alone: a square, or a circle. Its label is still what it is called.Button::new("Settings").variant(ButtonVariant::Ghost).icon(icons::SETTINGS).icon_only(true);Button::new("Add").icon(icons::PLUS).icon_only(true).shape(ButtonShape::Pill);
// While what it started is under way.Button::new("Saving…").loading(saving.get());| Builder | |
|---|---|
variant(variant) | Primary (the default), Secondary, Outline, Ghost, Destructive, or a variant the theme’s recipe names |
size(size) | Xs 28, Sm 32, Md 36 (the default), Lg 40, Xl 44, or a size the recipe names |
shape(shape) | ButtonShape::Default, the theme’s radius for a control, or Pill, rounded all the way |
icon(name), trailing_icon(name) | An icon before and after the label, by its name in the theme’s set. It is drawn in the color of the label, at the size the button’s size has for it |
icon_only(bool) | The icon alone: a square as wide as it is high, a circle with ButtonShape::Pill. The label is not drawn. An icon with an empty label and nothing else beside it is drawn so too |
loading(bool) | A spinner turns in the place of the icon, or before the label, and a click, Enter and Space do nothing until it is over |
description(text) | A second line under the label that says more of what the button does. The button is as high as the two lines, with an icon of 20 beside them |
leading(element), trailing(element) | Any element before and after the label, where an icon by name is not enough |
disabled(bool) | It takes no input: no press, hover or focus, and Tab passes it by. It is dimmed to the theme’s OpacityLevel::Disabled |
full_width(bool) | As wide as what it is in |
fill_label(bool) | The label (and its description) takes the room the button has: what is before it stands at the button’s start, what is after it (a trailing_icon, a trailing element) at its end, as a select’s chevron does. Seen on a button wider than its content (full_width, a width of the app’s). State ButtonState::FillLabel |
description_wraps(bool) | The description goes on to the next lines in the room the button has, in place of one line cut with an ellipsis: an answer that says what a press of it leads to. State ButtonState::DescriptionWraps |
on_click(handler) | A click, and Enter and Space while it is focused |
on_focus(Fn()) | Called when the button takes the focus: Tab, the arrows of a group it is in, the app, or a press of a button Tab stops at (one that is not, tab_stop(false), no press focuses). What is said beside it may follow the button the keyboard is on. A second handler is called after the first |
on_open_aside(handler) | Called, given the press, when a person asks for what the button opens beside what is open, in place of pressing it: the middle button, or a press with Ctrl held (Cmd on macOS), and Enter with it while it is focused. An app with tabs opens the place in a new one, and one the person switches to where the press’s shift is held. Such a press is the handler’s alone: no on_click, no focus, no submit, and nothing around the button hears it. See pointer-only pressables |
tab_stop(bool) | false: Tab passes the button by and a press leaves the focus where it was; focused by the app it is pressed by Enter and Space as before. See pointer-only pressables |
autofocus(bool) | The focus goes to it as the dialog, the popover or the menu it is in opens, in place of their first stop of Tab: a dialog’s main action, which Enter then does. It is a stop of Tab as it was, in its place |
state(name, on) | A state the theme’s recipe names |
style(part, |s| ...), rules(&recipe) | One instance over the theme; the rules of the place it is in |
force(Some(Interaction::Hovered)) | Drawn hovered, pressed or focused with nothing pointing at it: for a gallery, a screenshot, a test. A component made of items (segments, tabs, rows, titles, links) draws it on one item, the one Tab would stop on, as it can only be |
id(id), key(key), submit(bool) | Its id and key; with the form feature, the button that submits the form it is in |
ref_element(element), focuses(&ElementRef) | The ref of its element, which an app focuses or measures; and what a press of it gives the focus to, in place of taking it itself: the text a button of an editor’s bar works on |
mount(ctx), tooltip(Tooltip) | The button with its tooltip, kept in ctx: an icon-only button with a label has its label as its tooltip, as a toolbar gives the icons in it; tooltip(..) gives it one of the app’s in place of that (the keys of a shortcut, another side, a tooltip for a button with words). A button with neither is built as it is. In a toolbar the button is given as it is, and the toolbar puts its tooltip on it |
| Size | Height | Padding | Label | Icon |
|---|---|---|---|---|
Xs | 28, Density::Compact | 10 | 12 | 14 |
Sm | 32, ControlSize::Sm | 12 | 13 | 16 |
Md | 36, ControlSize::Md | 16 | 13 | 16 |
Lg | 40, ControlSize::Lg | 20 | 13 | 18 |
Xl | 44, Density::Comfortable | 24 | 15 | 20 |
| Part | |
|---|---|
ButtonPart::Root | The button itself: its fill, size, padding, corners, focus ring |
ButtonPart::Label | Its text: 13/500 in the design |
ButtonPart::Icon | An icon given by name: its side (square(..)), and a color of its own if the part names one |
ButtonPart::Spinner | What turns while the button is loading |
ButtonPart::Description | The line under the label: 12, at the theme’s muted opacity, so that it is quieter than the label on any fill |
ButtonPart::Leading, ButtonPart::Trailing | The elements put before and after the label |
States a recipe styles: ButtonState::Disabled, FullWidth, Loading, IconOnly, Pill, Description (it has a description), FillLabel and DescriptionWraps, and hovered, pressed and focus-visible.
- In the design a button under the pointer has its variant’s hover fill (
PrimaryHover,SecondaryHover,DestructiveHover, andHighlightfor an outline or a ghost button), a button held down has theStatePressedveil over that, and one focused from the keyboard has the theme’s focus ring. A primary button held down has the veil over itsPrimaryfill: overPrimaryHoverthe veil is lost (black on near black in the light palette, white on near white in the dark), and a press would look like a hover. The board draws a pressed button in its hover fill. - A button is as wide as its label where it has room. In a room narrower than it (a fixed width,
full_widthin something narrow, a panel that cannot grow, a line of a row that wraps) it is never wider than what holds it: it keeps its padding and its icon, and its label (and its description) is cut with an ellipsis. The board draws no button with a long label; the ellipsis is what every one-line label of the design system does. A toggle does the same. An icon alone keeps its square. - A loading button shows three quarters of itself. It stays where the focus is and is not pressed: a form it submits is not submitted again. Its label is the app’s to change.
- A theme’s renderer for
ButtonPart::Label,ButtonPart::IconorButtonPart::Spinnerbuilds that part in place of the default one: dots that pulse where the design turns a ring. - A button that is an icon alone is still called by its label: tooling that reads the tree (DevTools, the MCP tools) names it so.
- The design’s close button, menu button and compound button are this button:
Button::new("Close").variant(ButtonVariant::Ghost).size(ButtonSize::Xs).icon(icons::CLOSE).icon_only(true),Button::new("Export").variant(ButtonVariant::Outline).trailing_icon(icons::CHEVRON_DOWN), and a button with adescription. - In a toolbar a button is a ghost one of the bar’s size (unless its item is
as_given), and an icon alone has a tooltip of its label. Where the bar is too narrow for it, it goes into the bar’s menu as an item of its label, its icon, its id with-itemafter it, disabled where the button is disabled or loading; choosing the item calls the button’son_clickhandlers with the click Enter would make (from_keyboard, at 0, 0).
Pointer-only pressables
Section titled “Pointer-only pressables”Many desktop apps reach their buttons, rows, tabs and links with the pointer and with their own shortcuts, and keep Tab for the fields of a form: a press of a toolbar’s button leaves the focus in the text being typed. A pressable of the design system is a stop of Tab unless it is told tab_stop(false), which a Button, a ListItem, a Tag (its remove button) and, once for all their items, Tabs, a SegmentedControl, a Breadcrumb and WindowTabs (its tabs, its add button and its More button) take:
use lurq::ui::{Breadcrumb, Button, ButtonVariant, Tab, Tabs, icons};
Button::new("Bold").variant(ButtonVariant::Ghost).icon(icons::BOLD).icon_only(true).tab_stop(false);Tabs::new(view, [Tab::new("board", "Board"), Tab::new("list", "List")]).tab_stop(false);Breadcrumb::new(["Projects", "Orchester", "KON-12"]).tab_stop(false);- Tab passes it by, forward and back; Tab from it, where it has the focus, goes on to the next stop as from anything else.
- A press with the pointer leaves the focus where it was: in the field being typed in, or nowhere. The press does what it does.
- It still takes the focus it is given:
Ctx::focus, an element ref, an agent through MCP. Focused, Enter and Space press it, a tag’s Backspace and Delete take the tag away, and the arrow keys of the tabs or the segments it is one of move along them as before. - It is the same to what reads the tree: its role, its name and its states do not change.
The engine’s elements have the two halves apart, for an app’s own control: tab_stop(false) passes an element by while a press still focuses it, as a browser’s tabindex="-1" does, and focus_on_press(false) keeps a press from moving the focus.
A press can also ask for a place beside what is open, as a link in a browser does: on_open_aside(handler) on a Button, a ListItem, a Tab, a BreadcrumbStep, a SidebarItem and a MenuItem (whose menu closes, as after a choice). The middle button, or the primary one with Ctrl held (Cmd on macOS), and Enter with the key while it is focused, call the handler in place of the press: the button’s on_click is not called, the tab is not selected, the step is not followed, the row’s path is not gone to, nothing takes the focus, no form is submitted, and what is around the control (a row that opens its own page) does not hear the press. A middle press starts no scroll that follows the pointer. The handler is given the press, so an app tells a tab that is switched to (Shift held) from one that opens behind (SidebarItem’s is given nothing). A control with no such handler takes these presses as it did.
use lurq::{app::events::MouseEvent, ui::ListItem};
ListItem::new("KON-12 Tasks list") .on_click(move |_| open(route.clone(), Where::Here)) .on_open_aside(move |press: MouseEvent| open(route.clone(), if press.shift { Where::NewTab } else { Where::Behind }));Toggle
Section titled “Toggle”A button that stays on until it is pressed again: bold in an editor, a filter that holds.
use lurq::ui::{Toggle, icons};
Toggle::new("Bold") .icon(icons::BOLD) .on(bold.get()) .on_change(move |on| bold.set(on));| Builder | |
|---|---|
on(bool) | Whether it is on. The toggle does not keep it: the app says so |
bind(Signal<bool>) | On while the signal is true, which a press turns; on_change handlers are called after it is set |
on_change(handler) | Called on a press with what the toggle is to be: on if it was off |
icon(name), icon_only(bool) | An icon before the label; the icon alone, a square. An icon with an empty label is drawn so too |
leading(element) | An element before the label, where an icon by name is not enough: the dot of a recording. It stands before an icon that is given too |
size(size) | A ToggleSize (a ButtonSize): a toggle is as high as a button of that size |
focuses(&ElementRef) | What a press of it gives the focus to, in place of taking it itself: the text a toggle of an editor’s bar works on. It is still a stop of Tab |
disabled(bool), state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them |
Parts: TogglePart::Root, Label, Icon. States: ToggleState::On, Disabled, IconOnly. In the design a toggle has no fill until the pointer is on it or it is on, and then the Highlight fill; it is padded 10.
In a toolbar a toggle takes the bar’s size, and an icon alone has a tooltip of its label. Where the bar is too narrow for it, it goes into the bar’s menu as a checked item, on while the toggle is: its label, its icon and its id with -item after it. Choosing the item calls on_change with the other state, as a press would.
Button Group
Section titled “Button Group”Buttons that belong together, joined into one shape.
use lurq::ui::{Button, ButtonGroup, ButtonGroupVariant, icons};
ButtonGroup::new([Button::new("Years"), Button::new("Months"), Button::new("Days")]).label("Period");
// An action and the choice of how to do it: a split button.ButtonGroup::new([Button::new("Merge").on_click(|_| merge())]) .variant(ButtonGroupVariant::Primary) .button(Button::new("How to merge").icon(icons::CHEVRON_DOWN).icon_only(true).on_click(|_| choose()));| Builder | |
|---|---|
ButtonGroup::new(buttons) | The buttons, in order |
button(button), buttons(buttons) | Buttons after the ones it has |
variant(variant) | Outline (the default): one line around the group and a line between its buttons, which have no fill. Primary, Secondary, Destructive: buttons in that fill, a pixel apart |
size(size) | The ButtonGroupSize (a ButtonSize) of every button in it |
label(&str) | What the group is called to what reads the tree, a group |
disabled(bool) | Every button in it is disabled. State: ButtonGroupState::Disabled |
state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. force draws the first button |
- The group gives its buttons their variant and their size and squares their corners: the corners of the group are the round ones. A button keeps the rest of what it was given: its icon, what a press does, whether it is disabled.
- Parts:
ButtonGroupPart::Root, the group;Item, what the group says of each button, laid over the theme’s recipe for a button’s root (padded 14 in the design);Separator, the line between two. - A split button is a filled group of two: the action, and a button that opens a menu hung from the group (
Menu::new(open, anchor).placement(Placement::BottomEnd), the group in an element that carries the anchor’s ref).
Toggle Group
Section titled “Toggle Group”Toggles that are one choice: one of them is on, or any number are.
use lurq::ui::{Choice, ToggleGroup, icons};
// One of them is on: the one with the signal's value.ToggleGroup::new(align.clone(), [(Align::Left, "Left"), (Align::Center, "Center"), (Align::Right, "Right")]);
// Any number are: those with the values the signal has.ToggleGroup::multiple(marks.clone(), [ Choice::new(Mark::Bold, "Bold").icon(icons::BOLD).icon_only(true), Choice::new(Mark::Italic, "Italic").icon(icons::ITALIC).icon_only(true),]);| Constructor | |
|---|---|
ToggleGroup::new(signal, choices) | Exactly one is on: a press of another sets the signal |
ToggleGroup::multiple(signal, choices) | A Signal<Vec<T>>: a press adds a value, or takes it out |
ToggleGroup::controlled(value, choices, on_change) | The app holds the one that is on: a press of another tells on_change (Fn(&T)) the value it is to be, and a press of the one that is on tells nothing |
ToggleGroup::controlled_multiple(values, choices, on_change) | The app holds those that are on: a press tells on_change (Fn(&[T])) the whole set it is to be |
on_change(handler) | Called as a person changes what is on, with the new value: |align: &Align| for a group of one, |marks: &[Mark]| for one of any number. Not called where the app sets the signal. Each one adds |
label(&str) | What the group is called to what reads the tree, a group; a field’s label where it has none |
orientation(Orientation) | Along a row (the default), or down a column, with the arrow keys of that way |
invalid(bool) | Its line is in the destructive color; a field’s judgment sets it |
size(size), disabled(bool) | For the whole group: a ToggleGroupSize (a ButtonSize) |
state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. force draws the toggle Tab stops on |
The group is generic over its values: new and controlled make a ToggleGroup<T>, whose on_change is told &T, and multiple and controlled_multiple a ToggleGroup<T, [T]>, told &[T]; the compiler checks what a handler is told. T is () where nothing names it, as in the theme’s resolve::<ToggleGroup>. A choice is a value and a label, (value, "Label"), or a Choice with an icon, the icon alone, or disabled. Tab stops in the group once; the arrow keys move between its toggles, and Space or Enter turns the one the focus is on. Parts: ToggleGroupPart::Root, Item (laid over a toggle’s root) and Separator. States: ToggleGroupState::Horizontal, Vertical, Disabled, Invalid.
In a toolbar the group takes the bar’s size and is no stop of its own: its toggles are among the bar’s controls, and the bar’s Left and Right move through them and on. Where the bar is too narrow for it, the whole group goes into the bar’s menu, after a line, as a checked item for each toggle, on while it is; choosing one presses that toggle.
Segmented Control
Section titled “Segmented Control”One of a few choices that are all in view, side by side on a track.
use lurq::ui::SegmentedControl;
SegmentedControl::new(period.clone(), [(Period::Day, "Day"), (Period::Week, "Week"), (Period::Month, "Month")]);
// The app holds what is chosen, and is told what it is to be.SegmentedControl::controlled(theme.preferred_appearance(), [(None, "System"), (Some(Light), "Light")], |look| { theme.set_preferred_appearance(*look)}).label("Appearance");| Builder | |
|---|---|
SegmentedControl::new(signal, choices) | The chosen segment is the one with the signal’s value; a press of another sets it |
SegmentedControl::controlled(value, choices, on_change) | The app holds the value: a press of another segment tells on_change (Fn(&T)) the value it is to be, and a press of the chosen one tells nothing |
on_change(handler) | Called as a person chooses another segment, with its value (|period: &Period|), checked by the compiler: the control is a SegmentedControl<T>. Not called where the app sets the signal. Each one adds |
label(&str) | What the control is called to what reads the tree, a group; a field’s label where it has none |
invalid(bool) | The track has a line in the destructive color; a field’s judgment sets it |
size(size) | A SegmentedControlSize (a ButtonSize): the track is as high as a button of that size |
full_width(bool) | As wide as what it is in, its segments sharing the width |
tab_stop(bool) | false: Tab passes its segments by and a press chooses one and leaves the focus where it was; the arrows move along them once the app focuses one. See pointer-only pressables |
disabled(bool), state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. force draws the segment Tab stops on: the chosen one, else the first that is not disabled |
- The control is one choice: Tab stops in it once, at the chosen segment; Left and Right move the focus to the next segment and choose it, Home and End the first and the last, and a click chooses one.
- A choice is a
(value, label)or aui::Choice:icon(name),icon_only(bool)anddisabled(bool), and of its ownid(..)(the segment’s id, after which its parts are named:<id>-label,<id>-count),count(n)(a number after the label, in the partCount, 12 inMutedForeground),state(name, on)(a state of the theme’s recipe on that segment alone, resolved over the control’s andSelected: a choice that warns) andelement_ref(ElementRef)(on the segment, for a popup it opens to hang from). A radio group draws the same; a toggle group and a chip group take a choice’sidandstate. - Parts:
SegmentedControlPart::Root, the track (Muted, padded 3, its segments 2 apart);Segment;Label;Icon;Count. States:Selected, of a segment (aBackgroundsurface with a small shadow);Disabled;FullWidth;Invalid.
Text that goes somewhere when it is pressed. It has no box, so it sits in a line of text or beside one.
use lurq::ui::Link;
Link::new("Read the docs").external(true).on_click(move |_| navigator.push("/docs"));// A page on the web: a press opens it in the browser.Link::new("lurq.dev").href("https://lurq.dev").external(true);| Builder | |
|---|---|
on_click(handler) | A click, and Enter and Space while it is focused. Where the link goes is what its press does |
href(&str) | The address a press opens in the browser (open_url), after the on_click handlers are told, unless one of them calls event.prevent_default(). An app with a router gives none, and goes to its route in on_click |
trailing_icon(name), external(bool) | An icon after the text; external(true) is the arrow of a link that leaves the app, where it has no trailing icon of its own |
disabled(bool), state(name, on), style(part, ..), force(..), id, key | As a button has them |
Parts: LinkPart::Root, Label (14/500), Icon (14, four after the text). While the pointer is on the link or the focus is in it, the label has an underline (a within rule: the root is an interaction group): a straight line under the text alone, not under the icon. The root’s own edge would curl up at its ends, rounded as it is for the focus ring.
A floating action button: the one thing a view is for, raised over it.
use lurq::ui::{Fab, icons};
Fab::new("Compose", icons::COMPOSE).on_click(|_| compose());Fab::new("Compose", icons::COMPOSE).extended(true); // with its label- It is a button that is an icon alone, round, 48 across, with an icon of 20 and the theme’s large shadow, and takes what a button takes:
variant,on_click,disabled,loading. - Parts:
FabPart::Root,Icon,Label, each laid over the theme’s recipe for the same part of a button. States:FabState::Extended,Disabled,Loading(a button’s own rules dim it and turn its spinner).state(name, on),style(part, ..),rules(&recipe),force(..),idandkeyas a button has them. - Where it floats is the app’s to say: it is an element, put in a corner of a
Stack. A container clips what is in it, so give its shadow room, or let the container show what is outside it (.overflow_visible()).
Switch
Section titled “Switch”A setting that is on or off and takes effect at once: dark mode, sync in the background.
use lurq::ui::Switch;
// Bound to the app's signal, which a press turns.Switch::new("Dark mode").bind(dark.clone());
// The app holds it, and is told of a press.Switch::new("Reduce motion") .on(motion.get()) .on_change(move |on| motion.set(on));
// The track alone, in a row of settings that has the text already.Switch::new("Sync in background").label_hidden(true).bind(sync.clone());| Builder | |
|---|---|
on(bool) | Whether it is on. The switch does not keep it: the app says so |
bind(Signal<bool>) | On while the signal is true, which a press turns: on and a handler that sets the signal |
on_change(handler) | Called on a press with what the switch is to be: on if it was off. Bound, it is called after the signal is set, and not when the app sets it. A second handler is called after the first |
invalid(bool) | What it holds is wrong, where a field says so: the track is edged in the destructive color |
label_hidden(bool) | The track alone. The label is still what the switch is called |
label_wraps(bool) | The label goes on to more lines within the width the switch is given, the track beside its first line and centered on it (the line in the track’s middle where the track is the taller); the switch is then no wider than what holds it. Not unless told: the label is on one line |
whole(bool) | The track and the label are one control: the root is what is pressed, focused and ringed, one stop of Tab, and the id is on it, the parts named after it (x-track, x-thumb, x-label). State SwitchState::Whole |
element_ref(ElementRef) | Refers to what is pressed and focused once it is laid out: the track, or the whole where it is whole. What a screen moves the focus to (ctx.focus(&element)), or a popup hangs from |
disabled(bool), state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. id is the id of the track, or of the whole where it is whole |
- A press of the track or of the label asks for the other state. Tab reaches the track, Space and Enter press it, and the focus ring is the track’s; a whole switch’s are the root’s, round the track and the label, with the small radius.
- A press of a switch or of its label is the switch’s alone: a row around it that is pressed (a list item, a row of settings with its own press) is not pressed by it.
- Parts:
SwitchPart::Root(the track and the label, side by side),Track(what is pressed),Thumb,Label. States:SwitchState::On,Invalid,Disabled,Whole. - In the design the track is 36 by 20 and round, in the
Inputcolor and inPrimarywhile it is on; the thumb is 16, inBackground, 2 from the edge; the label is 8 beside the track in the body’s type. A disabled switch is dimmed with its label. The board draws no invalid switch: an invalid one has an edge of 1 inside its track inDestructive, as an invalid checkbox’s box has. A field with an error makes its switch invalid. - The thumb slides: the default renderer moves it by an offset, how far is
SwitchView::travel()(the track’s width less its padding and the thumb), and the recipe gives the thumb a transition ofTransition::offset_x()over the theme’s fast duration. A theme with reduced motion moves it at once. - To what reads the tree (
lurq_snapshotof the MCP server) the track is aswitchcalled by its label, witha11y_checkedsaying whether it is on. - A renderer that draws another switch starts from
view.track(), the behavior with the track’s style, and puts in it what it likes;view.thumb()is the default thumb. Whereview.wholeis true it starts fromview.whole_root(), the behavior with the root’s style, and puts the track and the label in it.
One line of text that a person types: a name, an email address, a search.
use lurq::ui::{Input, InputSize, icons};
Input::new(name.clone()).placeholder("Display name");
Input::new(query.clone()).placeholder("Search components").icon(icons::SEARCH).size(InputSize::Sm);
// What the app checked: the edge says so.Input::new(email.clone()).invalid(!email_ok);| Builder | |
|---|---|
new(Signal<String>) | What the input shows; what is typed is set on it, and what the app sets on it is shown |
placeholder(&str) | What it says while it is empty |
label(&str) | What it is called, to what reads the tree. It draws nothing: a field gives it its own label |
icon(name) | A glyph of the theme’s set at the start of the box |
size(InputSize) | Sm 32, Md 36 (the default), Lg 40 high, with text of 13, 14, 15 |
invalid(bool), warning(bool), valid(bool) | What the app judged of what it holds: the edge in the destructive, warning or success color. One is shown, in that order |
read_only(bool) | It is focused, selected and copied, and every edit is refused |
full_width(bool) | As wide as what holds it, in place of 260 |
error_icon(name) | An icon before the description while the field is invalid (its error, or a description of an invalid field): 14, 6 before the words, in their color, centred on them (part Icon). A field that is not invalid draws none |
control_end(bool) | The label and the description on the left, one over the other and 2 apart, taking the row’s room (part Text), and the control at the row’s end, 16 from them and in the middle of their height: a row of settings with its switch or select. The orientation is not read; a fluid field is not drawn so. State FieldState::ControlEnd; with full_width(true) as wide as what holds it |
on_input(handler) | Called before an edit with the TextInputEvent; prevent_default() refuses it |
on_submit(Fn(&str)) | Called with what it holds when Enter is pressed in it, with no modifier and outside a composition. A second handler is called after the first |
completion(&str), squiggles(ranges) | What would complete what is typed, drawn after it and taken by Tab; and wavy lines under ranges of its text, what the app’s spelling checker marks. See text editing |
name(..) | The name of its value in a form (feature form) |
disabled(bool), state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. id is the id of the control, the box that is typed in |
- It is the engine’s
TextInput, single line, dressed by the recipe: the control is the box, so that the ring of its focus is drawn on it. A text input is focus-visible however it was focused, so a click shows the ring too. Tab reaches it wherever it is (tab_index(0)). - Parts:
InputPart::Root(the place it takes: its width, and the room between the icon and the text),Control(the box: edge, fill, height, the type of the value),Placeholder(laid over the control’s type),Icon. States:InputState::Invalid,Warning,Valid,ReadOnly,Disabled,FullWidth,Icon. Sizes:InputSize::Sm,Md,Lg(InputSizeisTextBoxSize, which a textarea has too). - In the design the box is 260 by 36,
Backgroundin an edge of 1 in theInputcolor,radius-md, the text 12 from the edge in the body’s type, the placeholder inMutedForeground. The edge is the only signal of its state:Ringunder the pointer, a line of 2 inRinginside the box in the focus (an outline, so that the edge under the pointer does not take it away),Destructive,Warning,Successfor a judgment (which keeps its color under the pointer and in the focus). Disabled is half opaque onMuted; read only is onMutedin theBordercolor. The icon is 16 inMutedForeground(inSuccesswhile it is valid), 8 before the text. - In a field it is called by the field’s label unless it has a
labelof its own, it is judged as the field is unless the app judged the input itself, and it is disabled where the field is. - A text input does not take the foreground of its node, so the renderer names the color of the value and of the placeholder from the parts’ foregrounds (
InputView::value_style(),placeholder_style()). - To what reads the tree the control is a
textbox, witha11y_invalid,a11y_readonlywhere it is read only, and the name its label or its field’s gives it (InputView::label). - A renderer that draws another input starts from
view.control(), the bound text input in the control’s style;view.icon()is the icon laid over its start, andview.text_start()how far the text starts from the edge. - What an input and a textarea have in common is one recipe’s worth of rules on the box (its edge and fill, the focus inside it, the placeholder’s color, the judgments, read only, disabled, the type of the sizes): a theme that changes one of them for both patches each recipe, by the same part and state names.
A control with what it is called above it, and under it what it is for or what is wrong with what it holds. The field finishes its control: the label names it, a press of the label focuses it, and an input in a field with an error is invalid without being told.
use lurq::ui::{Field, Input, Orientation, ShortcutRecorder, Switch, Textarea};
Field::new("Display name", Input::new(name.clone()).full_width(true)) .description("Shown in the title bar.") .required(true);
// The error makes the input invalid: its edge is destructive.Field::new("Email", Input::new(email.clone()).full_width(true)) .error("Enter a full email address.");
Field::new("What happened", Textarea::new(story.clone()).full_width(true)).warning(true);
// Any element is a control; the label beside it, where a form lines its labels up.Field::new("Notifications", Switch::new("Pause notifications")).orientation(Orientation::Horizontal);
// A control that keeps state of its own: the field mounted where it is declared mounts it.Field::new("Command palette", ShortcutRecorder::new(palette.clone())) .description("Opens the palette from anywhere.") .mount(ctx);| Builder | |
|---|---|
new(&str, impl FieldControl) | Its label and its control: an Input, a Textarea, another component, any Element (an engine node goes in with .into()). An empty label draws none above the control and names it nothing: a checkbox with its own label beside it, and the field’s description under it |
description(&str) | What the control is for, under it |
error(&str) | What is wrong, in place of the description; the field is invalid |
invalid(bool), warning(bool), valid(bool) | The description in the destructive, warning or success color, and the control judged so |
disabled(bool) | Its control takes no input, and a press of its label focuses nothing |
required(bool) | A * after the label |
optional(bool), optional_text(&str) | ”Optional” after the label, or the app’s own words. A required field shows none |
info(&str) | What the label needs explained: the mark of an info label after the label, 6 after what is before it, with the words in a tooltip above it. The tooltip shows on a field that is mounted (mount(ctx)), and the mark is then the field’s first stop of Tab; on one converted into an element the mark says the words to tooling alone |
orientation(Orientation) | Vertical (the default): the label above the control. Horizontal: the label in a column of 110 beside the control and its description; the field is at least the label’s column, the gap and the control. States FieldState::Horizontal and Vertical |
full_width(bool) | As wide as what holds it, in place of 260 |
fluid(bool) | The label inside the box of the control, over what it holds: a fluid field |
Field::unlabeled(impl FieldControl) | A field with no label: the control alone with what the field says under it. The control keeps the name it has of its own (its hidden label, its label); no control takes an empty name from a field. Beside its label (Horizontal) the field keeps the label’s column, empty, so that its control is in line with the others of the form |
below(element) | An element of the app’s under the description, after those given before, one under another, 4 apart (part FieldPart::Below): rows of errors the control found, a count, a link |
state(name, on), style(part, ..), rules(&recipe), id, key | As a button has them. id is the id of the field’s root |
mount(ctx) | The field built where it is declared, its control mounted: see below. Converting it (.into()) builds it with its control as it is |
- A control that keeps state of its own between renders, which outside a field the app mounts, is mounted by a field the app mounts (
Field::mount(ctx)): the field tells it what it says, then mounts it (FieldControl::mount_in_field), and it is the same control in the field as outside it, with the field’s label, description and error. These are the shortcut recorder (it records), the date field and the time field (they keep what is half typed), the date picker, the date range picker and the time picker (they open), the month picker and the year picker (they keep the year shown), the password input (its eye turns), the rating (the stars under the pointer are lit), the file upload and the drop zone (a drag over them shows) and the listbox (a virtual list). A field converted into an element builds its control as it is converted, which keeps nothing: it shows its value and takes the field’s words, but does none of that. Any other control is the same converted or mounted. A mounted field goes in a fieldset as a child:.child(field.full_width(true).mount(ctx)). - A field is at least as wide as its control: one wider than the recipe’s 260 that does not fill the field (an input OTP of six cells) widens it, and the label and the description stay 260. Beside the label the field is at least the label’s column of 110, the gap of 12 and the control, and the description wraps in the 238 the recipe’s 360 leaves it. A description longer than the field wraps. Beside the label, a control lower than an input (a switch) stands in the middle of the label’s height, level with it.
- A field’s control is a
FieldControl: what the field tells it (InField: the label, the judgment, whether it is disabled, the description) it takes as far as it has the prop, and only where the app did not say it of the control itself: an input with a label of its own keeps it, and one the app judged keeps that judgment whatever the field says. A control of an app’s own implementsFieldControland passes what it is told to the control in it; one that keeps state of its own implementsmount_in_field(self, &InField, &mut Ctx)too, which tells it the same and mounts it (by default it isin_field). AnyElementtakes none of it.
| Control | Takes from a field |
|---|---|
Input, Textarea, Select | Its name (the field’s label), its judgment (invalid, warning, valid), disabled |
Checkbox, Radio | Its name where its own label is hidden (the label a person reads is then the field’s), invalid, disabled |
Switch | Its name where its own label is hidden, disabled |
CheckboxGroup, RadioGroup | Its name (label, on the group), invalid on every box or radio, disabled |
Slider, RangeSlider | Its name, disabled |
SegmentedControl, ToggleGroup | Disabled; each segment or toggle keeps its own name |
- The field’s description, or its error while it has one, is the control’s description to what reads the tree (
a11y_description), whatever the control: the field puts it on each outermost node in the control that says what it is (a11y_role) or takes the focus, so a radio group is described and not each radio in it.lurq_inspectreports it asdescription. - A press of the label focuses the control: the first node under what holds it that takes the focus (
.focuses(&ElementRef)on the label, the ref on the row that holds the control). A control that is disabled is not focused, and a disabled field’s label focuses nothing. A renderer that holds the control another way putsview.focuson what holds it. - An input or a textarea that is to fill the field says so (
Input::full_width,Textarea::full_width). - In a form. The form controls of
lurq::components(featureform) are these components bound to a form’s control:FormTextInputis a field holding an input (a textarea where it is multiline),FormCheckboxInputa field with no label above a checkbox with its label beside it,FormSliderInputandFormRangeSliderInputa field holding a slider as wide as it, andFormPrimaryButtonandFormSecondaryButtona primary and an outline button as wide as what holds them. The form’s error is the field’s error, a required control has the field’s mark, a disabled one (or one of a form that is submitting) is disabled, and every one of them is as wide as what holds it. They are styled by these recipes and no other: see Forms. - Parts:
FieldPart::Root,Label(the label and its mark),Required,Optional,Body(the control and the description, where the label is beside them),Description,Icon(the error’s),Text(the label and the description, where the control is at the end),Below(what the app put under the description). States:FieldState::Invalid,Warning,Valid,Horizontal,FullWidth,Fluid,ControlEnd,Disabled(no rule of the design’s: a theme dims what it likes). - In the design the field is 260 wide; the label is 6 above the control in a field label’s type (13, medium) and
Foreground, the description 6 under it in a caption’s (12) andMutedForeground. The*is 4 after the label, semibold, inDestructive; “Optional” is 11 inMutedForeground. Beside the control the label is 110 wide and as high as a control, 12 from it, and the field is 360 wide.
In a narrow room. A field whose label stands beside its control puts the label over the control where the field’s own room, not the window’s, is narrower than the two need side by side: the label is then as high as its text, and the control fills the row under it. With room again they stand side by side. The board draws the label beside its control (Fieldset, the horizontal field) and no narrow form of it: the label over the control is the form of its other fields.
Fluid Field
Section titled “Fluid Field”A field whose label is inside the box of its control, over the value: the design’s Fluid Field (imRnW), for a form whose fields stand edge to edge. It is a form of the field, Field::fluid(true), for the controls that have a fluid form, which every text control a field holds has: an input, a textarea, a select, a password input, a search field, a number input, a combobox, a multi select, a date field, a time field, a date picker, a date range picker, a time picker, a token input, a mentions field and a color field. A month picker and a year picker are panels of a grid, not boxes that hold a value: they have no fluid form.
use lurq::ui::{DatePicker, Field, Input, NumberInput, Select, Textarea};
Field::new("Workspace name", Input::new(name.clone())).fluid(true);
Field::new("Notes", Textarea::new(notes.clone()).rows(2, 5)) .fluid(true) .description("Shown to everyone in the workspace.");
Field::new("Theme", Select::new(theme.clone(), [("system", "System"), ("dark", "Dark")])) .fluid(true) .required(true);
Field::new("Seats", NumberInput::new(seats.clone()).min(1)).fluid(true);
// A control that keeps something between renders is mounted by the field, and has the form there too.Field::new("Due date", DatePicker::new(due.clone()).clearable(true)) .fluid(true) .mount(ctx);- The control is the box, as wide as the field: on
Muted, round at its top (6) and square at its bottom, with a line of 1 inForegroundalong its bottom and no edge on its other sides. The label lies over its top, 12 from its sides and 10 from its top, in a caption’s type (12) andMutedForeground, on one line, cut with an ellipsis where the box is narrower; the mark of a required or an optional field is after it, and the mark that explains it (Field::info) after that, which alone of the label takes the pointer, for its tooltip: a press elsewhere on the label goes to the control. What the control holds is 4 under the label’s line and 10 over the bottom: a control of one line is 56 high, a textarea as high as its rows and the 39 around them. The field is 240 wide, or as wide as what holds it (full_width). - The line says what the edge of a box says, where the board is silent: the ring’s color under the pointer,
Destructive,WarningorSuccessfor the field’s judgment (an error makes it destructive, as in any field),Borderwhen the control is read only. The focus is a line of 2 inside the box, as an input’s is. A disabled one is at half its opacity. - The description, or the error, is 6 under the box, as any field’s. A press of the label goes to the control under it: an input takes the caret, a select opens.
- What stands in the box beside the value stands on the line of the value, under the label, and not in the middle of the box: an input’s icon, a password’s eye, a search’s clear button, a picker’s button, a color’s swatch. The board draws the form for an input alone; the others follow it, each with what is particular to it:
- A password input has its eye 12 from the end of the box; its meter and what the meter says are under the box, as wide as it.
- A search field is padded 12 at its start, so that its icon starts where the label does; its clear button, or the hint of its key while it is empty, is at its end.
- A number input has its buttons on the line of the number, where its layout has them: each 25 high with the small radius, from the label’s line to 4 under the number’s, and the lines beside them as high. Stacked, they are one over the other about the number’s line, down to the line of the box.
- A combobox is a select’s fluid trigger: what is typed, the cross that clears and the chevrons are on one line.
- A multi select is at least 56 high. A tag (24) is higher than a line of text, so its box is padded 26 over its tags and 6 under them, and 12 at its start: with one line of tags, or with none, it is 56, and each line more adds a tag and the 6 between lines.
- A date field and a time field are 56 high, their segments and their glyph on one line, padded 9 at the start so that the first segment’s text starts where the label does.
- A date picker, a date range picker and a time picker are the input’s fluid box, with the button that opens the panel, and a clearable date picker’s cross, on the line of the value. A time picker, 160 wide on its own, is as wide as the field.
- A token input is padded 12 and 56 high on one line, its tokens in the middle of the line of its text; on rows it is as high as its rows (28 each) and the 39 around them.
- A mentions field is a token input on rows: its two rows of 21 and the 39 around them, and higher as its text takes more rows.
- A color field has its swatch and its eyedropper on the line of the hex; while its picker is open its line is in the ring’s color.
- A control says that it has the form with
FieldControl::has_fluid_form, and takes it when the field tells itInField::fluid: a control of an app’s own that wraps an input passes both on. A fluid field of a control that has none (a switch, a slider, a month picker) is drawn as any field, its label above the control. The label is always over the value: a fluid field’sorientationis not read. - States:
FieldState::Fluidon the field (itsLabeland itsRoot), and on the control the stateFluidof its own enum, namedfluid:InputState,TextareaState,SelectState,PasswordInputState,SearchFieldState,NumberInputState,ComboboxState(a multi select’s too),DateFieldState(a time field’s too),DatePickerState(a date range picker’s too),TimePickerState,TokenInputState,MentionsStateandColorFieldState. Its rules are on the part that is the box: theControl, theTriggerof a select, a combobox and a multi select, theRootof a date field and a time field. A renderer of a field hasview.fluidandview.fluid_label().
Info Label
Section titled “Info Label”What a field or a setting is called, with a mark after it that explains it: “API key”, and that it is stored in the keychain.
use lurq::{app::ctx::Placement, ui::InfoLabel};
InfoLabel::new("API key").info("Stored in the OS keychain").mount(ctx);
// The tooltip on another side, with an arrow.InfoLabel::new("Region") .info("Where the data of the workspace is kept") .placement(Placement::Bottom) .arrow(true) .mount(ctx);| Builder | |
|---|---|
new(&str) | The text of the label |
info(&str) | What the mark explains, in a few words: the text of its tooltip. Without one, or with an empty one, there is no mark |
info_label(&str) | What the mark is called to tooling, in place of “More information” |
icon(name) | The icon of the mark, in place of the “i” |
placement(Placement), offset(..), collision(..), arrow(bool) | Where the tooltip stands, as a tooltip has them. Above the label, from its start (Placement::TopStart), unless told |
force_open(Option<bool>) | The tooltip shown whatever the pointer and the focus do, or never |
mount(ctx) | The label where it goes, with its tooltip on it. Converting it (.into()) builds its still form: the label and the mark, on which nothing shows |
state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. id is the root’s, and the mark is <id>-mark; force draws the mark under the pointer or focused |
- The explanation is the theme’s tooltip, mounted on the label: it shows after the pointer has rested on the label or on its mark for the tooltip’s delay, and at once when the keyboard’s focus comes to the mark, which is a stop of Tab; it goes when they leave, on a press, and on Escape. It is a mounted component for that reason alone:
mount(ctx)puts the tooltip on it. - A label longer than the room it has ends in an ellipsis on its one line, and the mark keeps its place after it.
- To what reads the tree the mark is an
imgcalled “More information”, or byinfo_label, and described by what it explains (a11y_description), in the still form too. - A field draws the same mark after its own label:
Field::new(..).info("…"). An explanation with a link in it, or one that opens on a press, is a toggletip’s. - Parts:
InfoLabelPart::Root(the label and the mark, 6 apart),Label,Mark(the “i”: its side, its color, and its ring while it is focused from the keyboard). State:InfoLabelState::Info(it has something to explain). - In the design the label is a field label’s text (13, medium) in
Foreground, and the mark an “i” of 14 inMutedForeground6 after it; under the pointer and focused the mark is inForeground, and focused from the keyboard it has the theme’s ring around its circle. The board draws no state of the mark: these are a link’s. - A renderer that draws another label has
view.root(),view.mark()(Nonewith nothing to explain) andview.label; when the tooltip shows stays the label’s.
Textarea
Section titled “Textarea”Text of more than one line, typed into a box: a bio, a note, what happened.
use lurq::ui::{Textarea, TextareaSize};
// bio: Signal<String>Textarea::new(bio.clone()).placeholder("A few words about you");
// Two rows while it holds less, four before its text scrolls; wrong.Textarea::new(report.clone()).rows(2, 4).invalid(true);
// Read, selected and copied, not changed; in small type.Textarea::new(terms.clone()).read_only(true).size(TextareaSize::Sm);| Builder | |
|---|---|
new(Signal<String>) | What it holds. What is typed is written into the signal, and what the app writes there shows |
placeholder(&str) | What it shows while it holds nothing |
rows(min, max) | The rows it shows at least, and at most before its text scrolls inside it. 3 and 8 unless told (TEXTAREA_MIN_ROWS, TEXTAREA_MAX_ROWS) |
size(TextareaSize) | The type of an input’s sizes: Sm 13, Md 14 (the default), Lg 15, each with a line of 1.5. A row is that high |
invalid(bool), warning(bool), valid(bool) | What the app judged of what it holds: the edge in the destructive, warning or success color. One is shown, in that order |
read_only(bool) | It is focused, selected and copied, and every edit is refused |
on_input(handler) | Called before an edit with the TextInputEvent (new_value is what it will hold); prevent_default() refuses it. A read-only one makes no edit |
squiggles(ranges) | Wavy lines in Destructive under ranges of its text, bytes of it: what the app’s spelling checker marks. See text editing |
full_width(bool) | As wide as what holds it, in place of 260: in a form, as wide as its field. The state FullWidth |
name(..) | The name of its text in a form (feature form) |
label(&str) | What it is called, to what reads the tree. It draws nothing: a field gives it its own label |
disabled(bool), state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. id is the id of the box |
- It is the engine’s multiline
TextInput: as high as its text between its rows, its own scroll bar past them, Enter a new line. Tab reaches it wherever it is, as every control of the design system; a disabled one is passed by and takes no click. A read-only one is a stop of Tab and refuses every edit. - Parts:
TextareaPart::Root(the place it takes: its width, and its opacity while disabled),Control(the box, which is the text input: its edge, fill and padding, and the type and color of what it holds, as an input’s control),Placeholder(laid over the control’s type). States:TextareaState::Invalid,Warning,Valid,ReadOnly,Disabled,FullWidth. Sizes:TextareaSize::Sm,Md,Lg(TextareaSizeisTextBoxSize, an input’s sizes). - In the design the box is 260 wide, as an input is, in
Backgroundwith an edge of 1 inInput, the medium radius, padded 12 across and 8 down; its text is in the body’s type with a line of 1.5, inForeground, and the placeholder inMutedForeground. Under the pointer the edge isRing; focused, a ring of 2 is drawn inside the box, over the edge. Invalid, warning and valid, the edge and the ring areDestructive,WarningandSuccess. Read only, it is onMutedin theBordercolor, as a read-only input. Disabled, it is at the theme’s disabled opacity onMuted. Small, its text is 13; large, 15; the padding stays. - In a field it is called by the field’s label unless it has a
labelof its own, it is judged as the field is unless the app judged it itself, it is disabled where the field is, and a press of the label focuses it. - A text input draws in its own text style and does not take the foreground of what it is in, so the
TextandPlaceholderparts’ foregrounds are resolved to colors of the theme when the textarea is built (TextareaView::text_style,placeholder_style). - To what reads the tree it is a
textbox,a11y_multiline, witha11y_invalid,a11y_readonlywhere it is read only, and the name its label or its field’s gives it. - A renderer that draws another textarea starts from
view.input(), the behavior in the box’s style, and puts what it likes around it: a count of characters, a grip.
Checkbox
Section titled “Checkbox”A choice that is made or not, among others a form takes at once: send crash reports, keep me signed in, a row of a list picked.
use lurq::ui::Checkbox;
// Bound to the app's signal, which a press turns.Checkbox::new("Keep me signed in").bind(signed_in.clone());
// The app holds it, and is told of a press.Checkbox::new("Send crash reports") .checked(reports.get()) .on_change(move |checked| reports.set(checked));
// The box over a list of which some are picked: a press of it picks them all.Checkbox::new("Select all") .checked(picked == files.len()) .indeterminate(picked > 0 && picked < files.len());
// The box alone, in a row of a table that has the text already.Checkbox::new("Select blur.rs").label_hidden(true).checked(row.get());
// The mark alone, in a row pressed as a whole that says it is checked.Button::empty() .describe("a11y_checked", if bug { "true" } else { "false" }) .on_click(move |_| toggle_bug()) .child(Checkbox::new("Bug").checked(bug).mark_only(true)) .child(Text::new("Bug"));| Builder | |
|---|---|
checked(bool) | Whether it is checked. The checkbox does not keep it: the app says so |
bind(Signal<bool>) | Checked while the signal is true, which a press turns: checked and a handler that sets the signal |
indeterminate(bool) | Some of what it stands for is checked: a dash, whatever checked says |
on_change(handler) | Called on a press with what the checkbox is to be: checked if it was not, or was indeterminate. Bound, it is called after the signal is set, and not when the app sets it. A second handler is called after the first |
invalid(bool) | What it holds is wrong: the box is edged in the destructive color |
label_hidden(bool) | The box alone. The label is still what the checkbox is called |
label_wraps(bool) | The label goes on to more lines within the width the checkbox is given, the box beside its first line and centered on it: a label that may be long, such as one that names a folder. The checkbox is then no wider than what holds it, and a short label leaves it as narrow as before. Not unless told: the label is on one line |
name(..) | The name it has in a form (feature form): checked, it gives the form on, as the engine’s checkbox does, and nothing while it is not |
whole(bool) | The box and the label are one control: the root is what is pressed, focused and ringed, one stop of Tab, and the id is on it, the parts named after it (x-box, x-indicator, x-label). State CheckboxState::Whole |
element_ref(ElementRef) | Refers to what is pressed and focused once it is laid out: the box, or the whole where it is whole. What a screen moves the focus to (ctx.focus(&element)), or a popup hangs from |
mark_only(bool) | The box alone with its check or dash, for a row that is pressed as a whole (a filter’s option): no press, no focus, no stop of Tab and no label, hidden from what reads the tree, for the row is the control and says it is checked (a11y_checked on the row). In the recipe’s parts and states: checked, indeterminate, invalid and disabled look as they do. Its id and its element ref are on the box, its check x-indicator. CheckboxView::mark_alone() for a renderer |
disabled(bool), state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. id is the id of the box, or of the whole where it is whole |
- A press of the box or of the label asks for the other state; a press of an indeterminate one asks for checked. Tab reaches the box, Space and Enter press it, and the focus ring is the box’s; a whole checkbox’s are the root’s, round the box and the label.
- A press of a checkbox or of its label is the checkbox’s alone: a row around it that is pressed is not pressed by it.
- Parts:
CheckboxPart::Root(the box and the label, side by side),Box(what is pressed),Indicator(the check or the dash),Label. States:CheckboxState::Checked(checked and not indeterminate),Indeterminate,Invalid,Disabled,Whole. - In the design the box is 16 with the small radius, on the
Backgroundwith an inner edge of 1 inInput; checked or indeterminate it is filled and edged inPrimary, with the theme’scheckorminusicon of 12 (IconSize::Xs) inPrimaryForeground. An invalid box is edged inDestructive, checked or not. A disabled checkbox is dimmed with its label, and its box isMutedwhile it is empty. The label is 8 beside the box in the body’s type. - To what reads the tree (
lurq_snapshotof the MCP server) the box is acheckboxcalled by its label, witha11y_checkedtrue,falseormixed. - A renderer that draws another checkbox starts from
view.control(), the behavior with the box’s style, and puts in it what it likes;view.indicator()is the default mark,Nonewhile the checkbox is empty. Whereview.wholeis true it starts fromview.whole_root(), with the root’s style, and puts the box and the label in it. CheckboxGroup<T>is checkboxes over one list:CheckboxGroup::new(signal, choices)with aSignal<Vec<T>>checks the boxes whose values the signal has, and a press adds a value or takes it out;CheckboxGroup::controlled(checked, choices, on_change)leaves the list to the app, which is told the whole new set a press asks for (&[T]:checkedwith the value pressed added, or taken out) and draws what it says next.on_change(&[T])is told the whole new set after a press, bound or not, after the signal is set.orientation(Orientation)(Verticalunless told;Horizontalside by side, going on to the next line),label(&str)(its name to tooling: it draws nothing, a field gives it its label),invalid(bool)anddisabled(bool)are for the whole group, andChoice::disabledtakes one box out;state,style,rules,force(the first box that is not disabled),idandkeyare as a checkbox’s. Each box stays its own stop of Tab. Its parts areCheckboxGroupPart::Root(12 apart, or 24 side by side) andItem, laid over each checkbox’s root; its statesCheckboxGroupState::HorizontalandVertical, one of which is on. A theme’s renderer gets aCheckboxGroupView: its checkboxes built, inview.checkboxes, andview.render(). A theme names the group without its type (patch_recipe::<CheckboxGroup>), for groups of everyT.lurq::components::Checkboxis the engine’s node, which keeps its value in aSignaland draws its mark from an image;lurq::ui::Checkboxis the design system’s and does not use it. The engine’s is deprecated for an app since 0.63: see the migration guide.
One of a few choices that exclude each other, all of them in sight: the density of a list, the plan of an
account. RadioGroup is the choice; Radio is one radio, for a layout a group does not make.
use lurq::ui::{Choice, Radio, RadioGroup};
// The radio whose value the signal has is selected; a press of another sets it.RadioGroup::new(density, [(Density::Comfortable, "Comfortable"), (Density::Compact, "Compact")]);
// A choice that cannot be made, in a group with nothing selected until a press: a `Signal<Option<T>>`.RadioGroup::new(plan, [Choice::new("free", "Free"), Choice::new("enterprise", "Enterprise").disabled(true)]) .on_change(|plan| println!("{plan}"));
// The app holds the choice, and answers each press of another.let set = answer.clone();RadioGroup::controlled(answer.get(), [(true, "Yes"), (false, "No")], move |yes| set.set(Some(*yes))) .invalid(answer.get().is_none());
// One radio alone.Radio::new("Compact").selected(true).on_change(|selected| println!("compact: {selected}"));RadioGroup<T> | |
|---|---|
new(signal, choices) | The radio whose value the signal has is selected, and a press of another sets the signal: a Signal<T>, or a Signal<Option<T>> of which None selects none |
controlled(Option<T>, choices, on_change) | The app holds the choice: none while it is None; on_change is told the value of each radio pressed that was not selected, and what is drawn is what the app says next |
on_change(handler) | Called with &T, the value of a radio pressed that was not the one selected, after the signal is set. A press of the one selected calls nothing, nor does the app setting the signal. A second handler is called after the first |
orientation(Orientation) | Vertical unless told; Horizontal, the radios side by side, going on to the next line where there is no room |
label(&str) | What the group is called to tooling. It draws nothing: a field gives it its label |
invalid(bool) | Every radio’s edge in the destructive color: the choice was made wrongly, or not at all |
disabled(bool) | The whole group takes no input. Choice::disabled takes one choice out |
whole(bool) | Each radio pressed as a whole, as Radio::whole says; a choice’s id is then on its whole. The group is one stop of Tab still |
| choices | A (value, label) or a Choice, whose id(..) is its radio’s (its mark’s, its parts named after it: <id>-label, <id>-count), count(n) a number after the label, state(name, on) a state of the theme’s on its radio alone, and element_ref(..) a ref to its mark |
state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. force draws the radio Tab would stop on |
Radio | |
|---|---|
selected(bool) | Whether it is the one of several selected. The radio does not keep it: the app says so |
on_change(handler) | Called with true on a press while the radio is not selected. A press of the one selected calls nothing |
label_hidden(bool) | The mark alone. The label is still what the radio is called |
label_wraps(bool) | The label goes on to more lines within the width the radio is given, the mark beside its first line and centered on it; the radio is then no wider than what holds it. Not unless told: the label is on one line |
count(n) | A number after the label, in the part Count: 12 in MutedForeground |
element_ref(ElementRef) | Refers to the mark once it is laid out; to the whole where it is whole |
mark_only(bool) | The mark alone with its dot while it is selected, for a row that is pressed as a whole (a choice among grouped rows): no press, no focus, no stop of Tab, no label and no count, hidden from what reads the tree, for the row is the control and says it is chosen. Its id and its element ref are on the mark, its dot x-dot. RadioView::mark_alone() for a renderer |
invalid(bool) | The edge in the destructive color |
whole(bool) | The mark and its label are one control (state Whole): what is pressed, focused and ringed is the whole of them, one stop of Tab, a radio to tooling; its id is on the whole and the mark, the dot, the label and the count are named after it (x-mark, x-dot, x-label, x-count). RadioView::whole_root() for a renderer |
disabled(bool), state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. id is the id of the mark, or of the whole |
- A press of the mark or of the label selects the radio; a press of the one selected does nothing, so a choice
once made is not taken back. A group is one stop of Tab, at the selected radio or the first; the arrow keys
move the focus to the next radio and select it, Home and End the first and the last, and a disabled one is
passed by. A radio on its own is a stop of Tab that Space and Enter press. The focus ring is the mark’s, or the
whole’s. A press of a radio, its mark, its label or its whole, is its own: a row around it with an
on_clickof its own is not pressed by it, disabled or not. - Parts:
RadioPart::Root(the mark and the label, side by side),Mark(what is pressed),Dot,Label,Count. States:RadioState::Selected,Invalid,Disabled,Whole. A group’s parts:RadioGroupPart::Root(the radios one under the other, 12 apart) andItem, laid over the theme’s recipe for each radio’s root; its statesRadioGroupState::VerticalandHorizontal(side by side, 24 apart), one of which is on. A theme’s renderer of a group gets aRadioGroupView: its radios built, inview.radios, andview.render(). A theme names the group without its type (patch_recipe::<RadioGroup>,set_renderer::<RadioGroup>), for groups of everyT. - In the design the mark is 16 and round, in
Backgroundwith an edge of 1 inside it inInput; selected, the edge isPrimaryand a dot of 8 inPrimaryis in its middle. The edge of an invalid one isDestructive. The label is 8 beside the mark in the body’s type, and a group’s radios are 12 apart. A disabled radio is dimmed with its label. - A choice’s icon is not drawn: a radio is its mark and its label.
- To what reads the tree (
lurq_snapshotof the MCP server) the mark is aradiocalled by its label, witha11y_checkedsaying whether it is selected, and a group is aradiogroup. - A renderer that draws another radio starts from
view.mark(), the behavior with the mark’s style, and puts in it what it likes;view.dot()is the default dot.
Slider
Section titled “Slider”A value picked along a track, between a least and a greatest: volume, the size of a brush, a price no higher than. A range slider picks two on one track: a price between, the hours a shop is open.
use lurq::ui::{RangeSlider, Slider, SliderOrientation};
// volume: Signal<i32>Slider::new(volume.clone()).label("Volume");
// opacity: Signal<f32>: a fraction, in steps of a twentieth.Slider::new(opacity.clone()).step(0.05).label("Opacity");
// The app holds the value; told each change, and of the end of a drag.Slider::controlled(volume, move |value| set_volume(value)) .on_change_end(move |value| save(value));
// From 10 to 50 in steps of 5.Slider::new(size.clone()).min(10).max(50).step(5);
// Up, the least value at the bottom; 100 high.Slider::new(level.clone()).orientation(SliderOrientation::Vertical).length(100.0);
// price: Signal<(i32, i32)>, the low value first.RangeSlider::new(price.clone()).step(5).label("Price");| Builder | |
|---|---|
Slider::new(Signal<T>) | The value it is bound to, T a SliderNumber: i32, whole numbers from 0 to 100 in steps of 1, or f32, fractions from 0 to 1 in steps of a hundredth |
Slider::controlled(value, on_change) | The app holds the value, an i32 or an f32: the slider shows it, tells on_change what a person makes it, and shows what the app answers with. A drag goes on over the renders the answers make |
RangeSlider::new(Signal<(T, T)>), RangeSlider::controlled((low, high), on_change) | The two values of a range slider, the low one first, in the same ranges and steps |
on_change(Fn(f64)) | Each change a person makes, as it is made: a drag as it moves, a press on the track, a key. Not what the app sets, nor a new range or step that snaps the value. A range slider’s is Fn((f64, f64)), the two values. Each call adds |
on_change_end(Fn(f64)) | The value when a change is over, where it is another than it was as the change began: the drag let go, the press on the track or the key’s step made. A drag taken back to where it began tells nothing. A range slider’s is told the two. Each call adds |
min(v), max(v), step(v) | The least value, the greatest and how far apart the values are, from the least. Any number: min(10), step(0.25) |
orientation(SliderOrientation) | Horizontal, or Vertical: 16 wide and 140 high, the least value at the bottom. SliderOrientation is ui::Orientation |
length(f32) | How long the slider is along its track: its width across, its height up |
label(&str) | What the slider is called, to what reads the tree. The slider shows no text: the field it is in does |
name(..) | The name of its value in a form (feature form); a range slider gives its low value and its high one under it |
disabled(bool), state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. id is the id of the slider’s node |
- It is the engine’s
Sliderdressed by the recipe: a drag of the thumb, a press on the track and the keys set the signal, snapped to the step and kept in the range. Tab reaches it wherever it is (tab_index(0)), and the focus ring is the thumb’s. A vertical slider is dragged along its height, and the up and down arrows move it. - The keys: the arrows a step (right and up toward the greatest value), Page Up and Page Down a tenth of the range in whole steps and at least one, Home and End to the least and the greatest. The engine’s slider keys are the same for a vertical slider and for each thumb of a range slider.
- A range slider is the engine’s slider with two thumbs. A press on the track moves the nearer thumb, a drag the thumb it began on, and neither passes the other, by the pointer or the keys. Each thumb is a stop of Tab, the low one first; the keys move the one focused, and the ring is around it. In a form it is
FormRangeSliderInput(see Forms). - Parts:
SliderPart::Root(the slider’s node: its size, its cursor, its opacity),Track,Fill(the track from its start to the thumb, or between a range slider’s thumbs),Thumb(both of a range slider’s). States:SliderState::Disabled,HorizontalorVertical(one of them is on),Range. A range slider is drawn by the slider’s recipe and renderer in the stateRange, so a theme that restyles the slider restyles it too, andrules.state(SliderState::Range, ..)styles it alone. - In the design the slider is 240 by 16, and no longer than the room it is given: in a narrower row its track is shorter and its thumb stays on it, inside the slider, at every value; the track is 4 high and round, in
Secondary; the fill isPrimary; the thumb is 16, round, inBackgroundwith an edge of 1.5 inPrimaryinside it. The vertical one is 16 by 140, its track 4 wide and as high as it. A disabled slider is dimmed.style(SliderPart::Root, |s| s.width(Length::Fill))makes it as wide as what holds it. - The engine paints the track, the fill and the thumb, not nodes: of their style it takes the width and the height in pixels, the fill, the corners, the border and the outline (
focus_ring()too), at rest, under the pointer (hovered), and for the thumb focused from the keyboard (focus_visible). An opacity, a shadow or a transition of one of those three parts is not painted. On a vertical slider a part’s width is its thickness. - To what reads the tree (
lurq_snapshotof the MCP server) it is aslidercalled by its label; a range slider’s value islow,high. - A renderer that draws another slider starts from
view.slider(), the engine’s slider bound to the value (or the two) with its orientation, the root’s style and the length, andview.dressed(slider)gives it the recipe’s track, fill and thumbs.view.value()reads the value,view.values()a range slider’s two, andview.is_range()tells which it is.
Angle Slider
Section titled “Angle Slider”A dial that sets an angle in degrees, by a drag round it, a press on it or the keys: the rotation of a layer, the direction of a gradient or of a light.
use lurq::ui::AngleSlider;
// rotation: Signal<f64>, 0 to 360 in whole degrees, going round past 359 to 0.AngleSlider::new(rotation.clone()).label("Rotation");
// The app holds the angle; told each change, and of the end of a drag.AngleSlider::controlled(angle, move |angle| preview(angle)) .on_change_end(move |angle| save(angle));
// A half turn either way of 0, in steps of 15, held at its ends.AngleSlider::new(tilt.clone()).min(-180).max(180).step(15).wrap(false);| Builder | |
|---|---|
AngleSlider::new(Signal<f64>) | The angle the signal holds, in degrees; a drag, a press and the keys set it |
AngleSlider::controlled(f64, on_change) | The app holds the angle: it is told what a person makes it, and what is drawn is what it gives next |
on_change(Fn(f64)) | Each change a person makes, as it is made: a drag as it moves, a press, a key. After the signal is set; not when the app sets it, nor for a press that leaves it as it is. Each call adds |
on_change_end(Fn(f64)) | The angle when a change is over, where it is another than it was as the change began: the drag let go, the key’s step made. A drag taken back to where it began tells nothing. Each call adds |
min(v), max(v) | The range: 0 to 360 unless told. A range of more than a turn is turned round more than once |
step(v), page_step(v) | How far apart the angles are, from the least: 1 unless told, what an arrow key moves it by and what a drag snaps to. What Page Up and Page Down move it by: 15 unless told, in whole steps and at least one |
wrap(bool) | On unless told: where the range is a whole turn it goes round, a step past 359 is 0 and a drag goes on round. Off, or with another range, it stops at its ends, and a drag past an end stays there until it comes back |
label(&str) | What it is called to tooling, “Angle” unless told. A field gives it its label |
locale(&Locale) | The words it speaks in, its name, in place of the app’s (App::set_locale(Locale::for_tag("uk")), English where it set none), whose words are Locale::input. A label told by itself stays; the degrees are a sign, the same in every locale |
value_text(Fn(f64) -> String) | What it says the angle is, in its middle and to tooling: “45°” unless told, with the decimals of the step (“22.5°“) |
disabled(bool), state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. id is the id of the dial, what is dragged and focused |
- The angle is drawn as on a compass: 0 at the top and growing clockwise, the dot on the ring at it. An angle the app gives is snapped to the step and kept in the range; where it goes round, 370 is 10 and 360 is 0.
- The pointer: a press anywhere on the dial sets the angle it is at (of a range of more than a turn, the turn nearer to the angle it holds; past the ends of a range of less than a turn, the nearer end), and a drag goes on round from there, snapped to the step. A press at the dial’s very middle, where a point has no angle, sets nothing and the drag goes on from where it moves. A finger or a pen turns it as the mouse does, and is taken from the page. A press focuses it, so the keys go on from it.
- The keys: Right and Up a step clockwise, Left and Down a step back, Page Up and Page Down by
page_step, Home to the least and End to the greatest (where it goes round, the last step before it comes round to the least: 359). Each is a change and its end. Tab stops on it once; the ring of the focus is around the circle. - It tells as a slider does:
on_changefor each change, thenon_change_endfor the end of the drag or the key’s step; bound, the signal is set first. - It is built of boxes: the circle, the text in its middle and the dot, placed at the angle, so the parts are styled as any others are.
- In the design the dial is 64 on
Backgroundwith a ring of 1.5 inInputinside it, the angle in the mono type of 13 inForeground, and a dot of 9 inPrimaryinside the ring, touching it. The board draws it at rest: the ring of the focus is around the circle, the pointer is a hand over it, and a disabled dial is dimmed. A dial made larger (style(AngleSliderPart::Root, |s| s.square(96.0))) keeps its dot touching its ring. - To a screen reader it is a slider called by its label, of its range, that says its angle.
- Parts:
AngleSliderPart::Root(the circle, what is focused),Value,Handle. State:AngleSliderState::Disabled. - In a field it is called by the field’s label unless it has one of its own and disabled where the field is.
- A renderer that draws another dial is given an
AngleSliderView:view.root()is the dial with its behavior (the pointer, the keys, the role),view.value()andview.handle()the text and the dot,view.reach()how far the dot is from the middle,view.text()what it says,view.anglethe angle.
Rating
Section titled “Rating”A number of stars, chosen by a press or by the keys, or shown and not chosen: the quality of a call, how much a person liked a release, what others gave a package.
use lurq::ui::{Rating, RatingPrecision, RatingSize, icons};
// quality: Signal<f64>, 0 for none. Mounted, the stars up to the one under the pointer are lit as a press would set them.Rating::new(quality.clone()).label("Call quality").mount(ctx);
// review: Signal<Option<f64>>, None until a rating is given; in halves, and a press of the value takes it back.Rating::optional(review.clone()) .precision(RatingPrecision::Half) .clearable(true) .on_change(|stars| save(stars)) .mount(ctx);
// Shown and not chosen: an average lights the part of a star.Rating::at(3.7).label("Average rating").size(RatingSize::Sm);
// Another icon.Rating::at(3.0).icon(icons::HEART).empty_icon(icons::HEART);| Builder | |
|---|---|
Rating::new(Signal<f64>) | The stars the signal holds, 0.0 for none; a press or a key sets it |
Rating::optional(Signal<Option<f64>>) | The same where none is a state of its own: None until a rating is given |
Rating::controlled(f64, on_change), Rating::controlled_optional(Option<f64>, on_change) | The app holds the stars: it is told what a press or a key asks for, and what is drawn is what it says next |
Rating::at(f64) | Shown and not chosen from: the stars, the part of one too. It tells nothing and is no stop of Tab |
on_change(handler) | Called with what a press or a key sets (f64, or Option<f64> for an optional rating), after the signal is set. Not for a press that changes nothing, nor when the app sets the signal. Each call adds |
max(u32) | How many stars there are: 5 unless told |
precision(RatingPrecision) | Whole unless told; Half, a press of the half of a star under the pointer and the keys choose halves. A value the app gives is drawn as it is |
clearable(bool) | A press of the star that is the value takes it back to none; so do 0, Backspace and Delete |
read_only(bool) | Shown and not chosen from; at is a rating that is |
size(RatingSize) | Sm stars of 16, 2 apart; Md 20 and 4 apart, the board’s; Lg 24 and 4 apart |
icon(name), empty_icon(name) | The icon of a lit star and of one that is not: icons::STAR_FILL unless told |
label(&str) | What it is called to tooling, “Rating” unless told. It draws nothing: a field gives it its label |
value_text(Fn(Option<f64>, u32) -> String) | What it says it holds to tooling: “3 of 5 stars”, and “No rating” for none, unless told |
invalid(bool), disabled(bool), state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. id is the id of the row of stars, what takes the focus |
- To a screen reader it is a slider, the WAI-ARIA pattern for a rating that is one stop of Tab and takes halves: called by its label, of the range from none (or the first step where it is not clearable) to the number of stars, with its value in words. Tab stops on it once. Left and Down take a step off, Right and Up add one, Home and End go to the least and the most, a digit sets that many stars, and where it is clearable 0, Backspace and Delete set none. The ring of the focus is around the row of stars.
- The pointer: a press of a star sets that many, and in halves the half of the star under the pointer decides. A press focuses the rating, so the keys go on from it. Mounted (
mount(ctx)), the rating keeps where the pointer is, and the stars up to the one under it are lit as a press would set them; the pointer gone, the value is lit again. Converted into an element, or given to a field, it takes the presses and the keys and lights nothing under the pointer. - A value between two steps (3.7) is drawn as it is: the empty star, and over it the lit star in a room as wide as the part that is lit, which cuts the rest off.
- In the design the stars are solid, 20 and 4 apart, those lit in
Warningand the rest inInput. The board draws no other state: an invalid rating has its stars that are not lit inDestructiveat half its opacity, a disabled one is dimmed, and a rating that is chosen from has the pointer’s hand over its stars. - Parts:
RatingPart::Root(the row of stars, what is focused),Star(the room of a star, what a press chooses),Filled(a lit star, or the lit part of one),Empty. States:RatingState::Interactive,ReadOnly,Invalid,Disabled; sizesRatingSize::Sm,Md,Lg. - In a field it is called by the field’s label unless it has one of its own, invalid where the field is and disabled where the field is.
- A renderer that draws another rating is given a
RatingView:view.root()is the row with its behavior (the keys, the role, the value),view.star(index)a star with its room for a press,view.lit(index)how much of a star is lit,view.starsthe value andview.shownwhat is lit now.
Signature Pad
Section titled “Signature Pad”A surface a person signs on with a mouse, a pen or a finger: the signature on a delivery, the consent on a form. Behind the canvas feature.
use lurq::ui::{Field, Signature, SignaturePad};
// signature: Signal<Signature>. Each stroke let go, Undo and Clear set it.SignaturePad::new(signature.clone()).label("Signature of the recipient").mount(ctx);
// The app holds the signature, and is told what a person makes of it.SignaturePad::controlled(held.clone(), move |signature| save(signature));
// In a field, which names it and judges it.Field::new("Signature", SignaturePad::new(consent.clone()).placeholder("Sign to accept the delivery")) .error("Sign to accept the delivery.");
// The signature as a picture: its own size twice over, in the ink and the width given, on nothing.let image = signature.get().to_image(2.0, ink, 2.0); // Option<ImageData>let png = signature.get().to_png(2.0, ink, 2.0); // Option<Vec<u8>>, a PNG file| Builder | |
|---|---|
SignaturePad::new(Signal<Signature>) | The signature the signal holds; each stroke, Undo and Clear set it |
SignaturePad::controlled(Signature, on_change) | The app holds the signature: it is told what a stroke, Undo or Clear make of it, and what is drawn is what it gives next |
on_change(Fn(&Signature)) | Called after a stroke is let go, after Undo and after Clear, once the signal is set. Not while a stroke is drawn, nor when the app sets the signal. Each call adds |
placeholder(&str) | The words under the line, “Sign above the line” unless told. They stay once it is signed, as the board draws them, and end in an ellipsis where they do not fit; placeholder("") leaves the line alone |
read_only(bool) | It shows the signature and takes nothing: no stroke, no buttons, no stop of Tab |
full_width(bool), width(..), height(..) | As wide as what holds it; or a size of its own, 280 by 124 unless told, and no wider than what holds it |
label(&str) | What it is called to tooling, “Signature” unless told. A field gives it its label |
undo_label(&str), clear_label(&str) | The names of its two buttons, “Undo” and “Clear” unless told |
signed_text(&str), empty_text(&str) | What it says to tooling it holds: “Signed” and “Not signed” unless told |
locale(&Locale) | The words it speaks in, its name, the words under its line, its buttons’ names and what it says it holds, in place of the app’s (App::set_locale(Locale::for_tag("uk")), English where it set none), whose words are Locale::input. A word told by itself (placeholder, undo_label and the others) stays |
invalid(bool), disabled(bool), state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. id is the id of the pad, what takes the focus; its canvas is <id>-surface and its buttons <id>-undo and <id>-clear |
mount(ctx), build(theme) | Converted into an element, or mounted, it is the pad that is signed on: it keeps the stroke being drawn. build is its still form, which shows the signature and takes nothing |
- The value. A
Signatureis the app’s:strokes, each aSignatureStrokeofpointsin the order they were drawn, and thewidthandheightof the surface they were signed on. ASignaturePointisxandyin logical pixels from that surface’s top left,pressurefrom 0 to 1 where the input measures it (a pen, a screen that feels force;Nonefor a mouse) andtimein milliseconds from the first point of its stroke. A stroke of one point is a dot. It isClone,PartialEqand inspectable, to keep in a signal and to store. Given back to a pad of another size, it is drawn scaled to fit from its top left, keeping its shape, and a stroke drawn on it joins it in its own pixels. - The pointer. A press draws a stroke where the pointer goes until it is let go, and the stroke is shown as it is drawn; the signature is told only when it is let go. A move of less than three quarters of a pixel from the last point is no point. A stroke stays on the pad: one dragged past its edge goes along the edge. A finger or a pen draws as the mouse does, with its pressure, and is taken from the page: it does not scroll what the pad is in. A second finger while one draws draws nothing, and a touch the system takes away signs nothing.
- The line. Each stroke is a curve through the middles between its points (each point bends the line toward it), 2 wide in
Foregroundwith round ends and joins. The board’s line is even, so the pad’s is: its width does not follow the speed or the pressure, which are in the value for an app that draws otherwise. - The keys and the focus. The pad is one stop of Tab, and its Undo and Clear buttons the next two, in its top corner while it is signed. With the pad focused, Backspace takes back the last change, a stroke or a clearing, and Delete takes back every stroke. Its history is undo and redo to lurq (
on_undoandon_redo): Ctrl+Z (Cmd+Z on a Mac) takes back the last change and Ctrl+Shift+Z or Ctrl+Y (Cmd+Shift+Z) does again what was taken back, in a Ukrainian or any other layout, and so do an Edit menu’s Undo and Redo (ctx.edit(EditCommand::Undo)) with the pad focused. With nothing to take back, or to do again, the command goes on to what holds the pad: a form whose app keeps a history of its own. A new stroke forgets what was taken back, and a signature the app sets forgets what the pad did. A press or a stroke on the pad focuses it, so its keys go on from there; a press of Clear, or of Undo that takes back the last stroke, gives the focus to the pad, as the buttons are gone after it. A press of a button draws nothing under it. - A picture.
Signature::to_image(scale_factor, ink, line_width)draws it on lurq’s CPU canvas (CanvasHandle::offscreen) at its own size timesscale_factor, ininkandline_widthwide, on nothing: anImageDataof straight RGBA, the same wherever it is made and with no window.Signature::to_png(scale_factor, ink, line_width)is the same picture as the bytes of a PNG file (8-bit RGBA, not premultiplied), to store or to send; thecanvasfeature brings thepngcrate for it, which is Rust alone and builds for the browser.Signature::paint(&draw, width, height, ink, line_width)draws it on any canvas, scaled to fit. - In the design the pad is 280 by 124 on
Background, its cornersLg, an edge of 1 inInputinside it. At its bottom, 12 and 16 in, a line of 1 inInputand, 6 under it, the words in the mono type of 11 inMutedForeground. The board draws it signed and no other state: the ring of the focus is around the pad, Undo and Clear are ghost buttons of theXssize 6 in from its top corner, an invalid pad has its edge inDestructive, a disabled one is dimmed, and the pointer is a cross over a pad that is signed on. It is drawn on the canvas, again only when what it shows changes. - To a screen reader it is a picture (
img) called by its label and described as signed or not. - Parts:
SignaturePadPart::Root(the pad, what is focused),Surface(the canvas over the whole pad),Ink(the line: its background is the ink, its width the line’s),Guide(the column at the bottom: its padding and gap),Baseline,Placeholder,Actions(the row of the buttons). States:SignaturePadState::EmptyorSigned(one of them is on),Drawing,Interactive,ReadOnly,Invalid,Disabled. - In a field it is called by the field’s label unless it has one of its own, invalid where the field is and disabled where the field is.
- A renderer that draws another pad is given a
SignaturePadView:view.root()is the pad with its keys and its role,view.surface()the canvas that draws and takes the strokes,view.guide()the line and its words,view.actions()the buttons where they are shown,view.signaturethe value andview.draftthe points of the stroke being drawn.
Shortcut Recorder
Section titled “Shortcut Recorder”A box that holds a key combination, which a person sets by pressing it: the shortcut of a command in an app’s settings, the key that shows a window.
use lurq::{app::Accelerator, ui::ShortcutRecorder};
// palette: Signal<Option<Accelerator>>. Mounted, it records.ShortcutRecorder::optional(palette.clone()) .label("Command palette") // The app refuses a combination with a sentence the box says under it. .validate(|pressed| match pressed.to_string().as_str() { "Ctrl+Q" => Err("Already used by Quit".to_owned()), _ => Ok(()), }) .mount(ctx);
// The app holds it: told what is pressed, it shows what the app says next.ShortcutRecorder::controlled(saved, move |shortcut| store(shortcut.to_string()));| Builder | |
|---|---|
ShortcutRecorder::new(Signal<Accelerator>) | The shortcut the signal holds; a combination pressed and taken sets it |
ShortcutRecorder::optional(Signal<Option<Accelerator>>) | The same where none is a state of its own, which Backspace and the cross at its end give |
controlled(Accelerator, on_change), controlled_optional(Option<Accelerator>, on_change) | The app holds the shortcut: it is told what a combination pressed (or an emptying) asks for, and what is shown is what it says next |
on_change(handler) | Called with &Accelerator (&Option<Accelerator> for an optional one) after the signal is set. Not for the shortcut it holds already, nor when the app sets the signal. Each call adds |
validate(Fn(&Accelerator) -> Result<(), String>) | The app refuses a combination with a sentence: the box shows what was pressed, edged as wrong, says why under it, and keeps what it held. Each call adds a check |
require_modifier(bool) | A combination needs a modifier held with its key: it does unless told, but a function key is taken alone |
platform(KeyPlatform) | Whose names its keys are drawn with (Kbd): the platform the app runs on unless told |
label(&str) | What it is called to tooling: “Shortcut” unless told. It draws nothing |
placeholder(&str), recording_text(&str), clear_label(&str), modifier_text(&str) | What it says with no shortcut (“Record shortcut”) and while it records (“Press shortcut…”), what its cross is called (“Clear shortcut”), and what it says of a combination with no modifier |
size(ShortcutRecorderSize) | A box’s sizes: Sm 32 high, the board’s and the default, Md 36, Lg 40 |
invalid(bool), warning(bool), valid(bool), read_only(bool), disabled(bool), full_width(bool), name(..) | As an input has them. Read only, it does not record and has no cross. Its name gives the form its shortcut written as Ctrl+Shift+P |
state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. id is the box’s |
- A press of the box, or Enter or Space while it has the focus, starts recording. While it records it takes every key of the window (
captures_keys): the app’s own shortcuts and the accelerators of its menu are held back, and Tab is recorded with what is held. It shows the modifiers as they are held, and takes the combination when a key that is no modifier goes down (Accelerator::from_key_event). Escape gives up, the focus leaving it gives up, and Backspace and Delete with no modifier empty an optional one. - It records where it is mounted (
mount(ctx)), which keeps whether it records, the modifiers held and the combination it refused. Converted into an element it shows its shortcut and its cross empties it, but a press does not record. In a field the app mounts (Field::new("Shortcut", recorder).mount(ctx)) the field mounts it: it records, is called by the field’s label, judged as the field is, and disabled where it is, and a combination it refuses says why under it, over the field’s description. - In the design the box is 230 by 32, a box’s fill and edge with the medium radius, 8 in at its start and 6 at its end; its keys are
Kbds 4 apart, and the cross at its end is 14 inMutedForeground. Recording, its edge is a line of 2 inRing, and a dot of 8 inDestructivestands before “Press shortcut…” inMutedForegroundat 13. A refused combination edges it inDestructiveand says why 6 under it at 12 inDestructive. Under the pointer, judged, read only and disabled it is a box. - Parts:
ShortcutRecorderPart::Root,Control(the box),Keys,Dot,Hint,Clear,Message. States:ShortcutRecorderState::Recording,Empty,Refused,FullWidth, and a box’sInvalid,Warning,Valid,ReadOnly,Disabled. - To what reads the tree the box is a
buttoncalled by its label, witha11y_valueits shortcut in the platform’s words (“Ctrl+Shift+P”, “Cmd+Shift+P”),a11y_pressedwhile it records, and a refusal asa11y_invalidand itsa11y_description. - A renderer is given a
ShortcutRecorderView:view.control()is the box with its behavior,view.content()what it shows,view.clear()the cross,view.message()why a combination was refused,view.kbd(shortcut)the keys of a shortcut.
Select
Section titled “Select”One value chosen from a list that opens under a trigger shaped like an input: a theme, a time zone, a page size.
use lurq::{components::SelectOption, ui::{Select, SelectSize}};
// theme: Signal<String>Select::new(theme.clone(), [ ("system".to_owned(), "System"), ("light".to_owned(), "Light"), ("dark".to_owned(), "Dark"),]);
// Nothing chosen until the signal has an option's value; an option can have a detail, or be disabled.Select::new(zone.clone(), [ SelectOption::new("Europe/Kyiv".to_owned(), "Kyiv").detail("UTC+2"), SelectOption::new("Asia/Tokyo".to_owned(), "Tokyo").disabled(true),]).placeholder("Select a time zone").size(SelectSize::Sm).invalid(zone.get().is_empty());
// Groups with a label over each and a line between them, and a hint at an option's end.Select::new(platform.clone(), [ SelectOption::new("windows".to_owned(), "Windows").group("Desktop"), SelectOption::new("linux".to_owned(), "Linux"), SelectOption::new("ios".to_owned(), "iOS").group("Mobile").hint("beta"),]);
// Held by the app: it is told of a choice, and the trigger shows what it answers with.Select::controlled(rows, [(10, "10"), (20, "20"), (50, "50")], move |rows| set_rows(*rows));| Builder | |
|---|---|
new(Signal<T>, options) | What it is bound to, and its options: (value, label) pairs or SelectOptions (detail, a second line; hint, a note at its end; leading and trailing, an element before and after the label, which the closed select shows for the chosen option, and leading_with and trailing_with for one built for the state of its row, as an icon in the color of the label is; group(label), the group it starts; disabled). The option whose value the signal has is chosen; choosing another sets the signal |
optional(Signal<Option<T>>, options) | Bound to a value that may be none: None is no option’s, and the trigger shows the placeholder |
controlled(value, options, on_change) | The app holds the value: a choice is told to on_change, and the trigger shows what the app answers with. Two built at one place in the app’s code, in a loop, are told apart by their id or key |
on_change(Fn(&T)) | Called with the new value when a person chooses: not when the app sets the signal, and not for the option chosen already. The handler takes the type of the value, &Option<T> of an optional one: a Select<T> is generic over it, so a handler of another type does not compile. A second handler is called after the first |
placeholder(&str) | What the trigger says while no option is chosen |
size(SelectSize) | Sm 32, Md 36 (the default), Lg 40 high, with text of 13, 14, 15: an input’s sizes. SelectSize is TextBoxSize |
read_only(bool) | What is chosen is read and not changed: the list does not open. It keeps the focus; the trigger is on Muted in an edge of Border, as a read only input is |
invalid(bool), warning(bool), valid(bool) | What the app judged of what is chosen: the edge and the ring in the destructive, warning or success color. One is shown, in that order, as an input shows them |
full_width(bool) | As wide as what holds it, in place of 260 |
fit_options(bool) | Whether its list is as wide as its longest option, with the room of the check, in place of as wide as the trigger: for a trigger as wide as the one value it shows, as a bar’s control is. The panel’s min_width still holds |
label(&str) | What it is called, to what reads the tree. The field it is in shows its label |
name(..) | The name of its value in a form, the chosen option’s label (feature form) |
disabled(bool), state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. id is the id of the select’s node. state(SelectState::Open, true) draws the trigger as it is while open, for a gallery |
- It is the engine’s
Selectdressed by the recipe, not a second one: a press, or Enter, Space and the arrows from the keyboard, open the list under it (over it where there is no room); the arrows, Home, End and the first letters move through it, skipping disabled options and the groups’ labels; Enter or a press chooses, and Escape closes. Tab closes it too and goes on to the next stop, as from a closed select. Tab reaches it wherever it is (tab_index(0)); a disabled one does not open and Tab passes it by. - It stands beside an input: the same box, sizes, edge, ring and judgments. The ring is a line of 2 inside the box in
Ring, shown from the keyboard and while the list is open. - Parts:
SelectPart::Trigger(the select’s node and box: its size, edge, fill, padding, ring, opacity, cursor, the type of what it says, and in its gap the room before the chevron),ValueandPlaceholder(laid over the trigger’s type and color),Chevron(its side and color),Panel(the panel of the list: fill, edge, corners, shadow, padding; its gap is the room under the trigger, its height the most it is before it scrolls, and its least width how wide it is where its trigger is narrower),Item(an option: height, padding, corners, type, color;hoveredis the item under the pointer or the keys; its gap is the room before the check),Check(the chosen item’s mark),Detail,Hint,Group(a group’s label),Separator(the line between groups: its fill, its height, and in its padding the room around it). States:SelectState::Open,Invalid,Warning,Valid,ReadOnly,Disabled,FullWidth; an item’s ownSelectedandDisabledare resolved on its parts (Item,Check). Sizes:SelectSize::Sm,Md,Lg. - In the design the trigger is 260 by 36,
Backgroundin an edge of 1 in theInputcolor,radius-md, the text 12 from the edge in the body’s type, the placeholder and a chevron of 16 inMutedForeground, 8 apart;Ringunder the pointer;Destructive,WarningorSuccessfor a judgment, under the pointer, in the focus and open too; disabled is half opaque onMuted. The list is 4 under it and as wide, onPopoverin an edge ofBorder,radius-lg, with the theme’s middle shadow and 4 of padding. An item is 32 high, its text 8 in,radius-sm, in the body’s type, onHighlightunder the pointer or the keys; the chosen one has a check of 16 inForegroundat its end, 8 after the label; a disabled one is at 0.45. A hint is 11 in the mono type inMutedForeground. A group’s label is 11, semibold, inMutedForeground, in line with the items’ text; a line of 1 inBorderis between groups, 4 from each. - Its options follow the density: 24, 32 (the design’s), 40 and 44 high at compact, default, comfortable and touch, the steps of a row of 36 (28, 36, 44, 48). The trigger is a control and keeps its size.
- The engine paints the trigger, the panel and the rows itself, from its
SelectStyle, not from nodes the recipe styles: of the trigger it takes the fill, the edge, the corners, the shadow, the ring and the padding, at rest,hovered,focus_visibleand in the stateOpen; of an item, the fill, edge, corners, padding, height (at least), type, color and opacity, at rest,hoveredand in the statesSelectedandDisabled; of a group’s label, its padding, fill, type and color; of the separator, its fill, height and padding. A transition is not painted. - To what reads the tree (
lurq_snapshotof the MCP server) it is acombobox, called by its label where it has one. - A renderer that draws another select starts from
view.select_style(), the engine’sSelectStylethe recipe makes, changes what it likes (another chevron, a menu as wide as its widest option), and builds it withview.select(style), the engine’s select bound to the value with the trigger’s size, opacity and cursor.
Popover
Section titled “Popover”A panel beside the button that opens it, over the window, holding anything: the size of a layer, a few settings, a form. A press outside it or Escape closes it.
use lurq::{ components::Placement, ui::{Button, ButtonVariant, Field, Input, Popover},};
// open: Signal<bool>, anchor: ElementRef, width: Signal<String>Popover::new(open.clone(), anchor.clone()) .trigger(Button::new("Dimensions").variant(ButtonVariant::Outline)) .title("Dimensions") .description("Set the size of the layer.") .placement(Placement::BottomStart) .child(Field::new("Width", Input::new(width).full_width(true)).full_width(true));| Builder | |
|---|---|
new(open, anchor) | The app’s Signal<bool> of whether it is shown, and the element it is shown beside |
trigger(..) | The button that opens and closes it: put before it, given the anchor, and pressed to turn the signal |
title(&str), description(&str) | The text: what it is about, and under it what it is for. Without either there is no text |
child(..), children(..) | What it holds, one under another, as wide as the panel |
placement(Placement) | The side of the anchor it is on and the edge it lines up with. BottomStart by default |
width(..) | How wide the panel is, over the recipe’s 292 |
offset(impl Into<SpacingValue>) | How far it is from its anchor, away from it on the side it is on, over it too: SpacingSize::Xs (4) by default. A negative one moves it toward the anchor, over it |
cross_offset(impl Into<SpacingValue>) | How far it is moved along the edge it stands on: toward the end over or under its anchor, down beside it; a negative one the other way. A popover at a bar’s end, 12 in from it, is placement(Placement::TopEnd) and cross_offset(-12.0). None by default, and not used with at |
collision(CollisionStrategy) | What it does where there is no room on its side: FlipThenClamp by default |
within(element) | Kept inside the box of that element (an ElementRef), a column it belongs in, as well as inside the window: where its collision flips and clamps it, it does so in that box too (the engine’s Overlay::within) |
within_inset(element, Padding) | within the box of that element less the padding on each side (the engine’s Overlay::within_inset): a popover that ends 12 or more before its column’s end is within_inset(column, Padding::new().right(12.0)), and with CollisionStrategy::Clamp it moves back toward the start just as far as that takes |
placed_by(element) | Placed by the box of that element in place of its anchor’s: at its placement of that box, flipped and clamped there. The anchor stays its trigger and where the focus goes back: a popover over a status bar and at its end that an item of the bar opens (the engine’s Overlay::placed_by) |
at(Option<(f32, f32)>) | A point of the window it stands at in place of its anchor, its corner there, offset away, opening down and toward the end and the other way where there is no room (the engine’s Overlay::at). The placement is not used |
label(&str), described(&str), alert(bool) | What tooling calls it (its title by default), what it is described by, and whether it is an alertdialog |
on_dismiss(Fn()) | Runs after a person closed it by a press outside or Escape, not when the app sets the signal. Each handler given runs, in order |
dismiss_on_escape(bool), dismiss_on_outside_press(bool) | Whether Escape, and a press outside it and its anchor, close it: both true by default |
switch_on_anchor_press(bool) | Whether its anchor is the trigger of a dropdown: while another popup is open, a press of it closes that one and goes on to the anchor. true by default; false for a popover the app opens by itself at an element a press does something else to (a question at a card), where such a press only closes the other popup, as a press elsewhere does |
keeps_focus(bool) | It leaves the focus where it is as it opens, in the app’s field or panel, in place of taking it: a list of choices under a field being typed in, a calendar whose keys its panel reads (Calendar::keys(CalendarKeys::Panel)). A press outside it then goes on to what it was on, as well as closing it. false by default |
inline(bool) | Draws the panel where it is declared, open or not, without its trigger and not over the window: for a gallery, a screenshot, a test |
state(name, on), style(part, ..), rules(&recipe), id, key | As a button has them. id is the id of the panel |
- A title or a description longer than the panel wraps inside it.
- It is the engine’s
Popupwith the panel dressed by the recipe: it is placed against its anchor in every frame, goes to the other side where there is no room and is kept in the window (and in the elementwithinnames, as that element was last laid out: it flips where that box has no room on its side, is moved into it, then into the window, which wins where they differ; one wider than the box keeps its start at the box’s start), and closes on Escape and on a press outside it, which sets the signal tofalse. Declare it always and drive it with the signal: lurq only knows the anchor of a popup it can see. - With a trigger, the trigger’s own node is the anchor: a press of it, or Enter and Space on it, opens and closes the popover, and while another popup or select is open one press of it closes that one and opens this one. It tells what reads the tree
a11y_haspopupanda11y_expanded. Without a trigger the app opens it, and the anchor is any element of its own (ref_element); a press of the anchor is not a press outside it. - As it opens the focus goes to the first thing in it that takes the focus (
Popup::takes_focus), and as it closes with the focus inside, back to what had it when it opened: the trigger. Its stops of Tab come right after the trigger’s: Tab from its last one goes on to what follows the trigger. It does not keep Tab in it: it is not modal. - The anchor is kept from one render to the next (a field of the component,
ctx.element_ref()): one made anew in each render is not the one the focus goes back to. - It fades in over the theme’s
Baseduration in theEntercurve, and out overFastin theExitcurve (PartStyle::enter,PartStyle::exiton the root,FADE_INandFADE_OUT). A fade is not movement, so reduced motion leaves it. - A theme given to a subtree reaches a popover declared in it.
- Parts:
PopoverPart::Panel(the panel),Text(the title over the description),Title,Description,Body(what it holds). It has no states of its own. - In the design the panel is 292 wide in
PopoverandPopoverForeground, with an edge of 1 inBorder, theLgradius and theMdshadow, 16 of padding and 14 between the text and the body. The title is in the body’s type at medium weight, the description in 13 andMutedForeground, 4 under it; what the body holds is 14 apart. - To what reads the tree the panel is a
dialogcalled by its label or its title. - A renderer builds the panel alone: where it is shown, when, its trigger and its focus stay the popover’s. It starts from
view.panel(), the panel with its style and nothing in it, and hasview.text()andview.children.
A list of commands in a panel over the window, opened from an anchor: the actions of a file, the account’s menu, how a split button does what it does.
use lurq::{ components::Row, ui::{Button, ButtonVariant, Menu, MenuItem, icons},};
// anchor: ElementRef, open: Signal<bool>. The button the menu hangs from opens and closes it.let toggle = open.clone();Row::new() .ref_element(anchor.clone()) .child(Button::new("View").variant(ButtonVariant::Ghost).on_click(move |_| toggle.update(|open| *open = !*open)));
Menu::new(open, anchor) .item(MenuItem::new("Undo").icon(icons::UNDO).shortcut("Ctrl+Z").on_select(move || undo())) .item(MenuItem::new("Redo").shortcut("Ctrl+Y").disabled(true)) .separator() .item(MenuItem::new("Show grid").checked(grid.get()).on_select(move || toggle_grid())) .separator() .heading("Zoom") .item(MenuItem::new("Fit to window").radio(zoom.get() == Zoom::Fit).on_select(move || fit())) .item(MenuItem::new("100%").radio(zoom.get() == Zoom::Actual).on_select(move || actual())) .separator() // export: ElementRef, exporting: Signal<bool>: the submenu hangs from its item. .item(MenuItem::new("Export as").submenu(Menu::new(exporting, export).items(["PNG", "SVG", "PDF"].map(MenuItem::new)))) .item(MenuItem::new("Delete").icon(icons::TRASH).destructive(true).on_select(move || delete()));Menu | |
|---|---|
new(open, anchor) | Whether it is open, the app’s Signal<bool>, and what it hangs from (an ElementRef). Choosing an item, a press outside, Escape and Tab set the signal to false |
controlled(open, anchor, on_open_change) | A menu the app holds open itself, with a bool: a person closing it is told false, and what the app’s next render says is drawn. true and a handler that does nothing hold it open, for a gallery or a test |
item(MenuItem), items(..) | Commands, after what the menu holds already |
separator() | A line that ends one group of items and starts the next |
heading(&str) | A heading over the items after it: what they are about |
label(&str) | The menu’s name to what reads the tree |
placement(Placement) | Where the panel opens beside its anchor, 4 from it. BottomStart by default, RightStart for a submenu |
offset(impl Into<SpacingValue>), collision(CollisionStrategy) | How far the panel is from its anchor, along the side it opens on, in place of the design’s 4 (a submenu’s first item stays level with its item); and what it does where the window has no room on that side (FlipThenClamp, the other side, by default) |
on_dismiss(Fn()) | A person closed it other than by a choice: Escape, a press outside it, Tab. Not the app setting the signal. Each handler is called, in order. Tab in a submenu closes it and the menus it hangs from, and tells each one’s on_dismiss, the submenu’s first |
on_open_change(Fn(bool)) | Told false when a person closes it, by a choice too. Each handler is called, in order |
dismiss_on_escape(bool), dismiss_on_outside_press(bool) | Whether Escape and a press outside close it: both by default |
within(element) | Kept inside the box of that element besides the window, as a popover is; a submenu given nothing of its own is kept where its menu is |
placed_by(element), at(Option<(f32, f32)>) | Placed by the box of another element than its anchor, or at a point of the window, as a popover is; the anchor still opens it |
child(element), children(..) | Elements of the app’s among its entries, drawn as given: a foot that says why the items above cannot be chosen, a section of its own, a field. One is no item and does not close the menu; one that takes the focus is reached by the arrows as an item is |
scrolling(entries, max_height) | A section that scrolls where what it holds is higher than max_height (in logical pixels): see a section that scrolls |
entry(MenuEntry) | Any entry, after what the menu holds already |
submenus(SubmenuOpen) | What opens the submenus of its items: the pointer coming onto an item (SubmenuOpen::Hover, the default), or only a press of it, and Enter, Space and Right (SubmenuOpen::Press), where a press of an item whose submenu is open closes it and the pointer opens and closes none |
switch_on_anchor_press(bool) | Whether the anchor is the trigger of a dropdown, as a popover’s: false for a menu at the pointer over a row, or one the app opens by itself |
inline(bool) | The panel drawn where the menu is in the tree, open or not, and not over the window: for a gallery, a test, a list of commands in a page |
keeps_focus(&MenuKeys) | It leaves the focus in the app’s field as it opens, where a person goes on typing: see a menu that keeps the focus in a field |
page(Signal<Option<usize>>), back_label(&str) | Which item’s page the menu shows in its place, by the item’s place among what the menu holds (items, separators and headings counted), None for its own items; and what the row back is called before the page’s title (“Back”). A menu whose items have pages is given the signal; a person closing the menu sets it back to None |
state(name, on), style(part, ..), rules(&recipe), id, key | As a button has them. id is the id of the panel |
MenuItem | |
|---|---|
icon(name) | An icon before the label, by its name in the theme’s set |
leading(element) | Any element before the label, in place of the icon: an avatar, a mark of a service |
content(element) | All the item shows, the app’s own row, in place of its icon, label, detail and end. It is still the menu’s item: pressed, reached by the arrows and by typing its label, called by its label, checked, disabled or unavailable, and choosing it closes the menu. Its root is as high as the element and never lower than a row (state Content) |
detail(&str) | A second line under the label that says more of the item: an agent’s model under its name. The item is as high as its two lines |
unavailable(&str) | It cannot be chosen now, for this reason: disabled, in the state Unavailable, with a lock at its end and the reason under its label where it has no detail of its own. What reads the tree is told the reason (a11y_description). An empty reason makes it available again |
shortcut(&str) | The keys that do the same, written at the end: “Ctrl+Z”. The item only shows them; the app binds the keys |
checked(bool) | Whether what it turns on is on: a check at its end |
radio(bool) | One of several of which one is selected: a dot at the end of the selected one |
submenu(Menu) | A menu the item opens beside it, with a chevron at its end. The submenu’s anchor is given to the item |
page(items) | Items the item shows in its menu’s place, under a row that goes back with the item’s label for a title: a player’s “Quality” and its qualities. The item has a chevron at its end and is not chosen itself; choosing an item of the page closes the menu and calls that item’s handlers. An item has a page or a submenu, not both |
destructive(bool) | It removes or cannot be undone: drawn in the destructive color, icon and all |
on_select(handler) | Called when it is chosen, after its menu (and the menus it is in) closed, so that a handler that opens a dialog keeps the focus the dialog takes. Each handler is called, in order |
keeps_open(bool) | Choosing it calls its handlers and leaves the menu open, the focus (or the active item of a menu that keeps the focus in a field) where it was: an option of a filter that chooses several, checked as the app says. false by default. An item with a submenu or a page does that, and asking for it aside still closes the menu |
on_open_aside(handler) | Called in place of on_select when a person asks for what it stands for beside what is open: the middle button, a press with Ctrl (Cmd on macOS), Ctrl+Enter (Cmd+Enter) on the focused item or on the active item of a menu that keeps the focus in a field. The handler alone runs, given the press (its shift asks for a tab that is switched to), and the menu closes, with the menus it is in, as after a choice. An item that is disabled or opens a submenu or a page is asked for nothing. See pointer-only pressables |
disabled(bool), state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. id is the id of the item |
- The menu does not keep whether it is open: the app does, in the signal it gives it, and the anchor’s own handler opens it. Choosing an item sets the signal to
falseand then calls the item’s handler; a press outside the panel, Escape and Tab set it too (the engine’sPopup). Declare the menu always, open or not, beside its anchor: lurq then knows the anchor is its trigger. - The keyboard: a menu opened from the keyboard (Enter or Space on its button) has its first item focused and lit; opened by the pointer it has the focus there too, unlit. Up and Down move between its items and go round at the ends, Home and End go to the first and the last, and a disabled item is passed by. Typing a letter goes to the item whose label starts with it, letters typed quickly to the one a word starts, the same letter again to the next. Enter or Space chooses the focused item; the arrows only move the focus. Escape, or choosing, closes it and gives the focus back to its button. Tab closes it, and every menu it hangs from, and goes on from its button to the next stop, as Tab in an open select does (the panel is a focus group of one stop).
- The pointer and the keyboard are on one item: the pointer coming onto an item moves the focus there, and an arrow key moves the light off the item under a pointer that holds still.
- Under the pointer or focused from the keyboard an item is highlighted: filled with
Highlight, the board’saccent. An item whose submenu is open stays highlighted. - A submenu opens beside its item, its first item level with it, under the pointer (not in a menu given
submenus(SubmenuOpen::Press)), on a press of the item, or on Right, Enter or Space while the item is focused, with the focus on its first item; the pointer on another item of the menu closes it (where the pointer opens them), and so do Left and Escape while the focus is in it, giving the focus back to its item. Choosing in it closes it and every menu it hangs from, and gives the focus back to what opened the outermost, as choosing in the menu itself does. A press in the menu while a submenu is open closes the submenu and still reaches what it pressed. - Parts of the menu:
MenuPart::Panel,Separator(the room around the line),SeparatorLine,Label,Scroll(a section that scrolls); stateMenuState::Submenu. Parts of an item:MenuItemPart::Root(what is pressed),Icon,Leading(around the app’s element),Label,Detail,Lock,Shortcut,Check(the check or the dot),Chevron. States of an item:MenuItemState::Checked(a checked item),Selected(the selected radio),Radio,Destructive,Disabled,Open(its submenu is open),Detail(it has a line under its label),Unavailable(it cannot be chosen, for a reason;Disabledtoo),Content(it shows the app’s element),Active(the item the keys are on in a menu that keeps the focus in a field, filled withHighlight). - An item with a detail grows to its two lines, at least 32 high with 6 above and below them; its icon or element stands at the top, by the label. The detail is 2 under the label, in 12 of
MutedForegroundin lines of 1.4, and wraps where the menu has no room for it. An unavailable item is dimmed as a disabled one is, and ends in a lock of 16 inMutedForeground. - A menu is as wide as its widest item, and at least as wide as the design says; never as wide as the window. In the design the panel is at least 230 wide (a submenu 160) and, where the design has no longer label, at most 360: a label longer than that gives way with an ellipsis, and the shortcut, the check and the chevron keep their room and the 8 before them. The panel is in
PopoverwithPopoverForeground, padded 4, with the large radius, an edge of 1 inBorderand the medium shadow. An item is 32 tall, padded 8, with the small radius and 8 between what it holds: an icon of 16 inMutedForeground, the label in the body’s type, and at the end the shortcut in the mono type at 11 inMutedForeground, the check or the dot of 16, and the chevron of 16 inMutedForeground. A separator is a line of 1 inBorderwith 4 above and below; a group’s label is 11/600 inMutedForeground, 8 in from the side. A destructive item is inDestructive, its icon too; a disabled one is dimmed. - Its items follow the density: 24, 32 (the design’s), 40 and 44 high at compact, default, comfortable and touch. A context menu’s, a menubar’s and a command palette’s are menu items, and follow it with them.
- To what reads the tree the panel is a
menu; an item amenuitem, amenuitemcheckboxor amenuitemradio(these two witha11y_checked) called by its label; an item with a submenu hasa11y_haspopupmenuanda11y_expanded; a separator is aseparator. - What a menu holds, in order, is a
MenuEntry:Item(MenuItem),Separator,Heading(text),Element(element), an element of the app’s, orScroll { entries, max_height }, a section that scrolls, asMenuView::entrieshas them. AMenuItemconverts into one with.into(), for a list that mixes items with separators and labels, as a menubar’smenu(title, entries)takes. - A renderer for
Menugets aMenuView:view.panel()is the panel with its style and its focus group,view.item(item),view.separator()andview.heading(text)build what it holds, andview.render()hangs it from the anchor. A renderer forMenuItemstarts fromview.root(), the behavior with the root’s style, and puts in itview.icon()orview.leading(),view.label(),view.detail(),view.shortcut(),view.lock(),view.check(),view.chevron()or what it likes;view.submenu()is the submenu to put after it. Choosing it still closes its menu. - A menu of the app’s own rows keeps lurq’s menu: a
MenuItemgivencontent(row)is the row the app designs, with its label cut to its room, a detail on its line, a hint at its end, and the item is the root around it that the keyboard, the pointer and tooling know. The app’s recipe ofmenu_itemgives that root its height, its padding and its fill under the pointer; what the row draws for a state (dimmed, the destructive color, a lock) is the app’s, and the item still says the state to tooling. Rows that are not commands, a foot, a field, are the menu’schildren:
use lurq::ui::{Menu, MenuItem};
// open: Signal<bool>, anchor: ElementRef; row(..) and foot(..) build the app's elements.Menu::new(open, anchor) .item(MenuItem::new("Opus").content(row("Opus", "the deepest")).checked(true)) .item(MenuItem::new("Sonnet").content(row("Sonnet", "balanced")).unavailable("Not on this plan")) .separator() .child(foot("Sonnet is not on this plan."));A menu that keeps the focus in a field. The commands after a /, the people after an @, a combobox’s list:
the menu opens under a field a person goes on typing in, and the focus stays there (a combobox’s
aria-activedescendant). Menu::keeps_focus(&keys) takes a MenuKeys, made once by the app with the field’s
ElementRef, as a DateMemory is. The panel takes no focus, and a press of an item leaves the focus in the field;
one item is the active one (state MenuItemState::Active, a11y_selected to tooling), the first that can be chosen as
the menu opens and whenever what it holds changes, and the one the pointer comes onto. While the field has the focus
the panel reads its keys: Up and Down move the active item round the items that can be chosen, Enter chooses it,
Ctrl+Enter (Cmd+Enter on macOS) asks for it aside (MenuItem::on_open_aside), Escape closes the menu, and every other
key, letters and Home and End among them, is the field’s. Enter with no item that can be chosen is the field’s too. A
field whose own keys come first (Enter sends the message) forwards each key with MenuKeys::key_down(&event), which
says whether the menu took it; the menu takes a key once. MenuKeys::active() is the active item’s place among the
items. A press outside the panel, in the field too, closes the menu and goes on to what it was on; a press of the anchor
opens nothing. The items of a page and of a submenu are not reached by these keys.
use lurq::{ components::TextInput, ui::{Menu, MenuItem, MenuKeys},};
// field: ElementRef and keys: MenuKeys::new(field.clone()), both made once with the component; open: Signal<bool>.let menu = Menu::new(open.clone(), field.clone()) .keeps_focus(&keys) .items(commands.iter().map(|command| MenuItem::new(&command.label).on_select(command.run.clone())));let forward = keys.clone();let input = TextInput::new(draft.clone()).ref_element(field.clone()).on_key_down(move |event| { if forward.key_down(&event) { return; } // The field's own Enter: send.});- A section that scrolls.
Menu::scrolling(entries, max_height)(orMenuEntry::Scroll) is a section of the menu, the partMenuPart::Scroll(x-scroll,x-scroll-2…), that scrolls where what it holds is higher thanmax_height: the skills under a menu’s commands, the files after an@, a long list of branches. What it holds is the menu’s: its items close the menu, are named after the menu’s id in order with the rest, are reached by the arrows and by typing their label, and the one the focus goes to is scrolled into view. In a menu that keeps the focus in a field they are among the items the keys move, in order, and the active one is scrolled into view by the least that shows it; the section goes back to its top as the menu opens and whenever what it holds changes. An item’s place forpagecounts the section and then what it holds. A context menu’s bar has no room to scroll: what the section holds stands in the bar as the rest does.
use lurq::ui::{Menu, MenuItem};
// open: Signal<bool>, field: ElementRef, keys: MenuKeys; commands and skills are the app's.Menu::new(open, field) .keeps_focus(&keys) .items(commands.iter().map(|command| MenuItem::new(&command.label))) .separator() .scrolling(skills.iter().map(|skill| MenuItem::new(&skill.name)), 240.0);- A page is the menu’s other list in the same panel, where a submenu is a panel beside it: Right on an item with a page opens it, Left in the page and the row at its top go back, and the focus stays on the row the keyboard was on (the row back and the item that opened the page are one element to the engine). Parts
MenuPart::PageTitle(13/600) andPageIcon(the chevron, inForeground) style the row back, as the board’sMedia/Settings Menu/Pagehas it.
Dialog
Section titled “Dialog”A panel over the window that asks one thing and waits for the answer: delete a workspace, accept the terms, name a new file.
use lurq::ui::{Button, ButtonVariant, Dialog, DialogSize};
// open: Signal<bool>, the app's.let cancel = open.clone();Dialog::new(open.clone()) .title("Delete workspace?") .description("This removes every window layout and setting stored for this workspace. It cannot be undone.") .footer(Button::new("Cancel").variant(ButtonVariant::Outline).on_click(move |_| cancel.set(false))) .footer(Button::new("Delete").variant(ButtonVariant::Destructive));
// A body that scrolls between a header and a footer that stay, with a close button.Dialog::new(terms_open.clone()) .scrollable(true) .close_button(true) .title("Terms of use") .children(paragraphs) .footer(Button::new("Decline").variant(ButtonVariant::Outline)) .footer(Button::new("Accept"));| Builder | |
|---|---|
new(Signal<bool>) | Shown while the signal holds true. The dialog does not keep it: Escape, a press on the veil and the close button set it to false |
title(&str), description(&str) | What it asks, and more of it under the title. The title is what the dialog is called |
child(element), children(..) | The body: a form, a list, paragraphs |
footer(element) | Adds to the row at the end of the dialog, the least action first and the main one last. The app puts Buttons there |
size(DialogSize), width(impl Into<Length>) | Sm 360, Md 480, Lg 640, Full the window; 420 without one, the board’s, which is none of the steps. Never wider than the window |
scrollable(bool) | The body scrolls between a header and a footer that stay, each set off by a line |
icon(name), media(element) | A mark before the title: the icon in a well of 32 (Muted, radius-lg, the icon 16 in Foreground, 12 before the title, which then stands level with its middle), or the app’s element in its place, as it is. State DialogState::Mark |
note(&str), note_icon(name) | Quiet words at the start of the footer, the buttons at its end: why the action cannot be taken yet, what a key does. 12 in MutedForeground, an icon of 14 6 before them; they take the room the buttons leave, and wrap there. State DialogState::Note |
note_key(keys, words), note_key_worded(cap, words), note_child(element) | A key cap and the words of what the key does in the note, after its words, in the order given: note_key("Enter", "Delete").note_key("Esc", "cancels"). The keys are written as Kbd::shortcut writes them for the platform; note_key_worded writes the cap as the app gives it, its own word for the key (“Enter”, translated). The words are in the note’s type, 6 after the cap, and a pair stands 12 after what is before it (part DialogPart::NoteKey, ids <id>-note_key, <id>-note_key-2; each cap is a Kbd named by the part NoteKeyCap, <id>-note_key_cap, <id>-note_key_cap-2). note_child puts any element of the app’s there: it gives way where the note is short and is never wider than it, so a long reason wraps on to the next lines. A note of keys alone is a note |
inset_top(f32) | How much of the top of the window the veil leaves to what is under it, over the title bar of a window chrome, which it leaves without being told: a bar the app draws itself. That band takes the pointer as while no dialog is open, and the panel stands in the middle of the rest; the keys are the dialog’s |
initial_focus(DialogFocus) | Where the focus goes as it opens: FirstControl, the default, to a control marked autofocus (the main action) else its first stop of Tab; or Panel, to the panel itself, a stop of Tab before its first control that shows no ring, so that Enter confirms (on_confirm) and presses no button. As it closes the focus goes back to what had it, either way |
on_confirm(Fn()) | Called when Enter is pressed while the dialog is open: its main action, which the app runs (and closes the dialog after where it should). Not where the focus is on what Enter does a thing of its own with (a button, which Enter presses; a link; a select; a text input of several lines, where it starts a line), which the engine says in KeyboardEvent::focus_takes_enter, nor for an Enter an input method composes or one with Ctrl, Alt or Cmd held. An Enter in a text input of one line confirms. A dialog drawn inline confirms only an Enter from its own focus. A second handler is called after the first |
close_button(bool), close_label(&str) | A ghost button with the close icon at the end of the header, and what it is called to tooling: “Close” when not given |
dismiss_on_veil(bool), dismiss_on_escape(bool) | Whether a press on the veil, and Escape, close it. Both on by default |
on_dismiss(Fn()) | Runs after a person closed it: a press on the veil, the close button, or Escape wherever the focus is (the engine’s Modal::on_dismiss). A button of the app’s that closes it, or the app setting the signal, does not run it. A second handler runs after the first |
label(&str) | What it is called to tooling, over its title: for a dialog whose title is drawn by what it holds. described(&str) is what it is described by |
alert(bool) | An alertdialog to tooling, and not a dialog: it asks something that has to be answered |
inline(bool) | The panel where it is declared, without the veil and without taking the window: for a gallery, a screenshot, a test |
state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. force draws the close button as under the pointer, pressed or focused; id is the panel’s; key tells two dialogs of one component apart |
- A title or a description longer than the panel wraps inside its padding, beside the close button where there is one; neither is cut.
- It is the engine’s
Modalwithtarget(Root)andtakes_focus(true): declared anywhere, it takes no room there and covers the whole window while it is open. As it opens the focus goes to its first control (the close button where it has one), or to the control markedautofocus, or to its panel (initial_focus), and as it closes back to what had it, the button that opened it. Nothing under the veil takes the pointer, and Tab and Shift+Tab go round the dialog’s own controls. A dialog or a command palette opened while it is open is over it, wherever either is declared: it takes the focus, the keys and the pointer, Escape closes it first, and as it closes the focus goes back into the dialog under it. - A press on the panel goes no further: only a press on the veil itself closes the dialog.
- The panel is never larger than the window less the veil’s margin of 16. A dialog is as high as its content while that fits, and its body gives way and scrolls when it does not, in either form;
style(DialogPart::Panel, |s| s.height(300.0))gives it a height of its own. - Parts:
DialogPart::Veil,Panel,Header(the mark, the text and the close button),Mark,Icon(the mark’s),Text(the title over the description),Title,Description,Body,Footer,Note,NoteIcon,NoteKey,NoteKeyCap(rules over a cap’sKbd),Close(laid over the theme’s button),Separator(the lines of a scrollable dialog). States:DialogState::Scrollable,Mark,Note. Sizes:DialogSize::Sm,Md,Lg,Full. - In the design the panel is 420 wide in
Popoverwith an edge ofBorder, corners ofradius-xland thelgshadow, padded 24 with 20 between its text, its body and its footer; the veil isScrim. The title is 16/600, the description 8 under it in 14 ofMutedForeground, and the footer’s buttons stand at its end 8 apart. The scrollable one has a header of 56 (its title 20 from the edge, the close button 12 from it), higher for a description under the title, and a footer of 60, the body padded 20 and 16 between them: the body is as high as what is in it, and scrolls when the window has no room for all of the dialog. The close button is 28 with an icon of 16. - To what reads the tree the panel is a
dialogcalled by its label or its title. - A renderer that draws another dialog builds its panel from
view.panel(), the parts fromview.header(),view.mark(),view.text(),view.body(),view.note(),view.footer(),view.close()andview.separator(), and lays it over the window withview.modal(panel);view.closer()closes it, andview.dismisser()closes it and runs whaton_dismisswas given.view.panel()carries what Enter confirms with;view.confirmer()is that key handler, for a panel built another way.
Tooltip
Section titled “Tooltip”A short text beside an element while the pointer rests on it or the keyboard’s focus is on it: what an icon button does, and the keys that do it too.
use lurq::{ components::Placement, ui::{Button, ButtonVariant, Tooltip},};
// In a component's render: a tooltip is mounted on the element it describes, and returns that element.let copy = Button::new("Copy").variant(ButtonVariant::Ghost).icon("copy").icon_only(true);let copy = Tooltip::new("Copy").shortcut("Ctrl+C").mount(ctx, copy);
let zoom = Button::new("Zoom in").icon("zoom-in").icon_only(true);let zoom = Tooltip::new("Zoom in").placement(Placement::Bottom).arrow(true).mount(ctx, zoom);
// A disabled button shows its tooltip too: it can say why it is disabled.let export = Button::new("Export").disabled(true);let export = Tooltip::new("Nothing to export yet").mount(ctx, export);| Builder | |
|---|---|
mount(ctx, element) | Puts the tooltip on the element it describes and returns that element |
shortcut(&str) | The keys of a shortcut, after the text in a chip of their own |
note(&str) | A second line under the text that says more of it; the text is then its title, in a medium weight |
mono(bool) | Its text is a path, a command or code: in the theme’s mono family |
max_width(..) | The widest the box is before its text wraps, in place of the recipe’s 200 |
when_cut(&ElementRef) | It shows only while the text whose ref this is is cut: a label that says itself whole in its tooltip only where it is not whole already |
hint(&str) | With when_cut, what it says while the text is whole, in place of nothing; while the text is cut it says its own text. The element is described by the hint |
over(&ElementRef) | Keeps clear of that element, one around the element it describes, on the side it opens on: its distance from the frame’s edge, and along it lined up with its element (the engine’s Overlay::clear_of). A chip’s tooltip over the field the chip sits in |
hang(&anchor, open) | Not mounted on an element: the tooltip beside anchor, shown while open is (a bool or a Signal<bool>), an element to put among the children of any container. The app shows it and puts it away; the pointer, the focus, a press and Escape do nothing to it, and it takes no pointer |
placement(Placement) | The side of the element it is on and the edge it lines up with: Top, centered, by default |
offset(..), collision(CollisionStrategy) | How far it stands from the element in place of the theme’s 6, and what it does where there is no room on its side: FlipThenClamp by default |
arrow(bool) | A triangle from the box to the element |
open_delay(..), close_delay(..) | A MotionDuration of the theme’s or a Duration: how long the pointer rests before it shows (TOOLTIP_DELAY, 500 ms) and how long it stays after the pointer left (100 ms) |
force_open(Option<bool>) | Some(true) shows it whatever the pointer and the focus do, Some(false) never: for a gallery, a test, a tour |
disabled(bool) | It never shows, and the element is as it would be without it |
state(name, on), style(part, ..), rules(&recipe), id, key | As a button has them. id is the id of what shows |
- A text too long to have its shortcut beside it wraps across the box, no wider than 200 (or its
max_width), and the shortcut goes under it. A note wraps in the same box, under its title. - A tooltip
when_cut(&label)readsElementRef::text_cut(), what the last layout drew of the label: cut where it was ended by an ellipsis (TextOverflow::Elipsis) or by a limit of lines. While the label is whole the pointer and the focus show nothing, and the label is not described by the tooltip to what reads the tree, as it says the same itself. A label cut with an ellipsis, mounted as it is, is cut in the row the tooltip holds it in, which gives way as the label would:
use lurq::{components::{Text, TextOverflow}, ui::Tooltip};
// label: ElementRef, kept in a field of the component.let words = Text::new(path).nowrap().text_overflow(TextOverflow::Elipsis).ref_element(label.clone());let words = Tooltip::new(path).mono(true).max_width(400.0).when_cut(&label).mount(ctx, words);- It shows after the pointer has rested on the element for its open delay, and at once within
TOOLTIP_SKIP_DELAY(300 ms) of the pointer leaving another: along a toolbar each button’s shows at once, and the one before goes, so one tooltip of the pointer shows at a time. - Focus from the keyboard shows it at once: the focus of the element or of anything in it (a row with a button in it), read by
ElementRef::focus_visible_within(). - The pointer can be moved onto the tooltip to read it: it goes its close delay, 100 ms, after the pointer has left both the element and the tooltip. It also goes when the focus leaves, when the element is pressed, and on Escape; after a press or Escape it stays away until the pointer comes again, or until both the pointer and the focus have left.
- Escape is the tooltip’s before anything under it: the tooltip is the top layer that takes Escape, so the key closes the tooltip and not the dialog or the popup it is shown in.
- A disabled element shows its tooltip: a disabled element is not hovered, but it hears the pointer come and go, and the tooltip is on it as on any other.
- It is kept in the window: where there is no room on its side it is on the other one, its arrow turned with it, and where the window pushes it along, its arrow still points at the middle of the element. It takes no focus.
- A tooltip the app shows itself, as a toolbar shows its buttons’ tooltips the moment the pointer comes to them, is hung beside its anchor and not mounted:
Tooltip::new("Copy").placement(Placement::Bottom).hang(&anchor, shown)among the button’s children. It takes no pointer, so a press that comes with the pointer reaches the button under it. - To what reads the tree (
lurq_snapshotof the MCP server) the element is described by the text (a11y_description), and called by it (a11y_name) when nothing else names it: a text in the element names it (a button by its label), and an icon-only button is named by its label already; an icon alone, a glyph, names nothing. What shows is atooltip. An element with an element ref of its own keeps it, and the tooltip is anchored to it. - It is a mounted component, not a builder that goes where an element goes: it keeps timers for its delay and its grace, an anchor that stays the same from one render to the next, and whether the pointer has shown it, and a builder has no
Ctxto keep them in. Converted into an element on its own, aTooltipis its box as it shows, anchored to nothing: for a gallery, a test or a host of an app’s own. - Parts:
TooltipPart::Root(the box and its arrow, and the room between them and the element),Panel(the box),Label,Note,Shortcut,Arrow. The side it is on is the recipe’s variant (TooltipSide: the side of its placement, or the other where there was no room), and the states areTooltipState::Arrow,Shortcut,Multiline(the text wraps, known once it is laid out),NoteandMono. - In the design the box is in
Primarywith a radius ofMd, its text inPrimaryForegroundin the caption’s 12, 10 from its sides and 6 from its top and bottom, and no wider than 200; a text that wraps has 8 above and below it, in lines of 1.4. A note is 2 under the text in 12 of the regular weight in lines of 1.4, the text over it in a medium weight, and the box has 6 above and below them. A mono tooltip’s text is in the mono family. A shortcut is 8 after the text in a chip 16 high, 4 from its sides, with a radius of 3, in a white of 15%, its keys in the mono family in 10. The arrow is 12 along the box and 6 out from it, in the box’s color. The tooltip stands 6 from the element: the root’s padding on the side’s axis. - The arrow is a square in the box’s color turned by 45°, its middle on the edge of the
Arrowpart that meets the box; the part clips it to the half that points away (TooltipView::arrow()), moved along the box byTooltipView::aim. - A renderer builds what shows, not when: it is given a
TooltipViewwith the text, the note, the shortcut, the side the tooltip is on, whether it has an arrow and its aim;view.panel()is the default box andview.arrow()the default arrow. - It has no
label: its text is its name and what describes the element. It has noon_dismissand nodismiss_on_escape: the app does not open it, and Escape always puts it away, as content that shows on hover must be dismissible.
A short message that something happened, in a corner of the window over everything, that leaves by itself: settings saved, a file moved to the trash, a connection that failed.
use lurq::ui::{Button, ButtonSize, ButtonVariant, Toast, ToastVariant, Toasts};
// In the root component's create, once, kept in a field of it.let toasts = Toasts::new();// In its render, mounted last, so that its layer is over every other.column.child(self.toasts.mount(ctx));
// Anywhere, with a clone of it.toasts.show(Toast::new("Settings saved").description("Your theme applies to every open window.").variant(ToastVariant::Success));toasts.show( Toast::new("File moved to trash") .description("theme-dark.json") .action(Button::new("Undo").variant(ButtonVariant::Outline).size(ButtonSize::Sm).on_click(move |_| restore())) .timer(true),);| Builder | |
|---|---|
Toast::new(title), description(&str) | What happened, and more of it under the title |
variant(impl Into<Name>) | A ToastVariant: Neutral (the default, no icon), Info, Success, Warning, Destructive: the icon and its color. A variant a theme adds has no icon of its own |
icon(impl Into<IconChoice>) | An icon of the theme’s set in place of the variant’s, or none: icon(None) |
action(Button | Link) | What can be done about it, before the close control: the one action, a second takes its place |
close_button(bool), on_close(handler) | Whether it has its close control (it has unless told otherwise), and what a press of it calls; a second handler is called after the first |
label(&str) | What it is called to tooling, in place of its title |
timer(bool) | A rail along the bottom edge that says how long it has left |
duration(Duration), persistent(bool) | How long a Toasts shows it (TOAST_DURATION, 5 s), or that it stays until it is closed |
state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. id is the id of the panel; force draws the close control |
Toasts | |
|---|---|
Toasts::new() | No toasts yet. It needs no Ctx: make it once and clone it into whatever shows a toast |
show(toast) -> ToastId, dismiss(id), clear() | Shows one in front of the others; takes one away; takes all away |
ids(), len(), is_empty() | The toasts shown and waiting, the oldest first |
mount(ctx), mount_at(ctx, ToastPosition) | What draws them and keeps their time: at the bottom right, or at TopLeft, Top, TopRight, BottomLeft, Bottom |
- A toast is a panel like any other component and can be put anywhere. Sent to a
Toasts, it is drawn by what theToastsmounts, in a layer over the window, clear of its safe area and under the title bar aWindowChromedraws: the layer takes a press only on the toasts, and Tab reaches their controls from the page as it reaches any other. - It leaves after its duration, on a press of its close control or of its action, when a finger throws it to a side or toward the window’s edge, and by
dismiss. While the pointer is on the toasts their time stands still, timers too, and runs on from there when it leaves. - Several are stacked: the newest in front, an edge of each of two others behind it, on the side away from the window’s edge. With the pointer on them they are laid out one over another, 10 apart, the newest nearest the edge: those behind move out from behind the front one, fading in, and move back and fade when the pointer has gone, so nothing jumps and no shadow is left to vanish. At most
TOASTS_SHOWN(3) are shown, and their time runs, those behind the front one too; the others wait in order. - A toast comes in from the window’s edge, fading in over the theme’s slow duration, and leaves toward it over the base duration. One that comes while another is shown comes in over it: the one that was in front stays where it is, and fades under the new one when that is in. With reduced motion it comes and goes at once.
- Parts:
ToastPart::Root(the panel),Content(what is in it above the timer, side by side),Icon,Text(the title over the description),Title,Description,Action,Close,Timer(the rail),Remaining(what is left of it); and the host’sViewport(how far from the window’s edges),List(the toasts one over another),BehindNear,BehindFar(the edges behind the front one). State:ToastState::Action. Variants:ToastVariant. - In the design the panel is 360 wide, in
Popoverwith an edge ofBorder, large corners and the large shadow; 16 inside it are the icon of 16 in the variant’s color (Success,Info,Warning,Destructive), 12 from the title (14, medium) over the description (13,MutedForeground), each going on to the next line where the panel has no room for it, and the close control of 16 inMutedForeground. With an action it is 14 high inside, centered on the action, and the title is 2 over the description. The timer is a rail of 2 inSecondarywith what is left inPrimary. Toasts are 16 from the window’s edges; the edges behind are 24 and 48 narrower than the panel, three quarters and half opaque. - To what reads the tree the panel is a
statuscalled by its label or its title, and its close control abuttoncalled “Close”. Tab reaches the action and the close control; Space and Enter press them. - A renderer that draws another toast starts from the view’s parts:
view.icon(),view.text(),view.action(),view.close()(the close control with its behavior) andview.timer().
A list of tabs of which one is selected, and the panel of the selected one under it or beside it: the sections of a settings page, the views of a record, the filters over a list.
use lurq::ui::{Tab, Tabs, TabsOrientation, TabsVariant, icons};
// section: Signal<&'static str>. Selecting a tab sets it.Tabs::new(section, [ Tab::new("general", "General").panel(|| general()), Tab::new("appearance", "Appearance").icon(icons::SETTINGS).panel(|| appearance()), Tab::new("advanced", "Advanced").disabled(true),]).label("Settings");
// A row over a line, with counts, the archived set apart.Tabs::new(memory, [ Tab::new("all", "All").count(7), Tab::new("memory", "Memory").count(9), Tab::new("archived", "Archived").count(0).separated(true),]).variant(TabsVariant::Line);
// The app holds which is selected, and is told the tab a person selects.Tabs::controlled(filter, [(0, "Overview"), (1, "Activity")], move |index| set_filter(*index)) .variant(TabsVariant::Pill) .orientation(TabsOrientation::Vertical);
// More tabs than the width holds, kept between renders.Tabs::new(canvas, [(0, "Canvas"), (1, "Layout"), (2, "Text")]) .variant(TabsVariant::Line) .overflow(true) .mount(ctx);| Builder | |
|---|---|
Tabs::new(Signal<T>, tabs) | The selected tab is the one with the signal’s value; selecting another sets it. A tab is a (value, &str) or a Tab |
Tabs::controlled(value, tabs, on_change) | The app holds which is selected: the tab of value, and on_change is told the value of each other tab a person selects |
on_change(Fn(&T)) | Told the value of the tab a person selects (a press, the arrow keys, the menu of the overflowing form), after the signal is set. Not what the app sets, nor a press of the selected tab (unless the tabs reselect). A second one is called after the first |
reselect(bool) | A press of the selected tab, and choosing it in the More menu, tells on_change its value again, the signal left as it is: a page whose selected tab is a place of its own, which a press opens again. Off unless told. The arrow keys never reselect, nor does an inert tab |
variant(TabsVariant) | Default: a muted rail with the selected tab lifted out of it. Line: a row over a line, the selected tab underlined. Pill: round tabs, the selected one in the primary fill |
orientation(TabsOrientation) | TabsOrientation is ui::Orientation. Horizontal (the default): the list along the top, the panel under it. Vertical: the list down the start side, the panel beside it |
manual(bool) | The arrow keys move the focus alone, and Enter or Space selects: for panels slow to build. Otherwise the selection follows the focus |
label(&str) | What the list is called to what reads the tree |
overflow(bool) | The overflowing form: the list scrolls between two scroll buttons, and More at its end opens a menu of every tab |
note(&str), end(element) | Quiet words at the end of the list’s line (a caption in MutedForeground, 16 from the tabs, part TabsPart::Note), and an element of the app’s after them (8 from them, part End): why a tab cannot be opened, a button that acts on the page. They give way first where the line is short, the words ending in an ellipsis; the element is no tab, and the arrow keys pass it by. In the default form they stand in the rail; in the overflowing form at the end of the list that scrolls |
reserve_selected_width(bool) | Each label keeps the room it takes in the selected tab’s style, a heavier weight, selected or not: a copy so drawn, no higher than nothing and hidden from tooling, holds it. Selecting another tab then moves none after it, as a browser’s tab bar keeps its tabs in place. Off unless told; tabs that give way in a room too narrow (built with nothing kept) keep no room |
tab_stop(bool) | false: Tab passes the tabs and the More button by, and a press selects a tab and leaves the focus where it was; the arrows move along them once the app focuses one. The panel is a stop as before. See pointer-only pressables |
mount(ctx) | Puts the tabs in the tree of the app’s component, where the overflowing form keeps where its list is scrolled and whether its menu is open. Converted into an element on their own (build(theme), Element::from), the tabs are the still form: scrolled to the start, a menu that does not open |
more_label(&str), scroll_back_label(&str), scroll_on_label(&str) | The words of the overflowing form: what the More button says and is called (it says “More” and is called “More tabs” unless told otherwise), and the names of the scroll buttons, “Scroll back” and “Scroll on” |
disabled(bool), state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. disabled makes every tab disabled. force draws the tab Tab stops on, the selected one, and not the panel. id is the root’s; in the overflowing form the scroll buttons are <id>-back and <id>-on and the More button <id>-more |
Tab::new(value, label) | A tab. icon(name) before the label, count(n) after it, badge(n) a count of what waits for the person in a pill after them (part Badge, its id <id>-badge), disabled(bool), disabled_reason(&str) disabled and why (see below), separated(bool) a separator before it (a rule between groups of tabs), dot(PaletteColor) a dot of 6 in a role of the palette after the count and the badge (part Dot, <id>-dot), count_pending(bool) a bone as wide as a digit in the count’s place while the count is read (in the part Count, <id>-count, the bone CountSkeleton; the tab says a11y_busy), inert(bool) a tab a press leaves alone (drawn as it is, selected or not, but no press, menu item or arrow key selects or focuses it; state TabsState::Inert), trailing_icon(name) an icon after the label, the count, the badge and the dot (part TrailingIcon, <id>-trailing_icon, 14 square): the lock of a tab not built yet, at_end(bool) the tab stands at the end of the line along the top, after the room that grows, the note and the app’s element, with the other tabs so placed, as far apart as the list’s tabs (a page’s Settings after its lists; it is still a tab of the list, its arrow keys reach it after the tabs at the start and the More menu lists it in its order; mounted tabs count it in what the list needs to stand whole; down the side it stands after the others), state(name, on) the tab alone in a state the theme’s recipe names, which every part of it sees beside its own states (a count of what waits in Warning: recipe.when(Selector::new().state("waits"), TabsPart::Count, ..)), tooltip(Tooltip) and hint(&str) a tooltip on the tab whether it can be selected or not, in place of a reason’s (see below), panel(Fn() -> Element) what it shows while selected, on_open_aside(handler) called for the middle button or a press with Ctrl (Cmd) in place of selecting it (see pointer-only pressables; its item in the More menu is chosen as before), id (its item in the More menu is <id>-item), key |
- Exactly one tab is selected, and the app holds which. A press of a tab selects it; a press of the selected one or of a disabled one asks for nothing, and tells nothing. Tabs that
reselecttellon_changeof a press of the selected one, and set nothing. - The list is one stop of Tab, at the selected tab. The arrow keys of the orientation (Left and Right, or Up and Down) select the tab after and the one before, Home and End the first and the last, and a disabled tab is passed by; with
manual(true)they move the focus and Space or Enter selects. Tab from the list goes to the panel, and on to what is in it. - A tab disabled with a reason (
Tab::disabled_reason) is a disabled tab whose reason is its tooltip, shown as the pointer rests on it, and its description to tooling (a11y_description). A tab given a tooltip of the app’s (Tab::tooltip,Tab::hint) shows it whether it can be selected or not, an explanation beside a lock on a tab that opens; on a disabled tab it takes the place of the reason’s tooltip, the reason staying its description. A renderer gets the tab with its tooltip fromview.tab_element(index)(view.tab(index)is the button alone);TabEntryhas thereason, thebadgeand the tab’s ownstates. - The panel of a tab is built only while the tab is selected, keyed by the tab, so one tab’s panel never takes another’s nodes. What the runtime keeps of a panel’s nodes (a scroll offset, a caret, an open select) goes when another tab is selected; what the app keeps in its own signals stays. A panel that is to come back as it was keeps its state in the app: its values in signals made in the app’s
create, its scroll in aScrollStateit gives the scroll area (with_scroll_state). - The panel is a stop of Tab itself, so a panel with nothing focusable in it is still reached and read; its ring is the color and width of the focus ring, 4 out from the panel, clear of what runs to its edges.
- Parts:
TabsPart::Root(the list and the panel),List,Tab(what is pressed and focused),Label,Icon,TrailingIcon,Count,Badge(lurq’s, the board has none: a pill ofPrimarypadded 6 and 1, its count 11/500 inPrimaryForeground, the other way round on a selected pill tab),Dot,CountSkeleton(7 by 10),Separator,Note,End,Panel, and in the overflowing formBar(the row of the list, its buttons and More),ScrollButton,ScrollIcon,More,MoreLabel,MoreIcon. A tab’s parts are styled in its states:TabsState::Selected,Disabled,Inert; the whole hasHorizontalorVertical, andOverflow. Variants:TabsVariant::Default,Line,Pill. - In the design the default list is a rail of
Muted,radius-lg, padded 3, its tabs 2 apart; a tab is 28 high, padded 12,radius-md, its label 13/500 inMutedForegroundand a count of 12 inMutedForeground6 after it; the selected tab isBackgroundwith the small shadow and its label inForeground. The line list is 44 high over a line of 1 inBorder, as wide as what holds it, its tabs 28 apart; a label is 14 inMutedForegroundand a count 13 at 0.7, 8 apart; the selected tab is underlined with 2 inForeground, its label 500 inForegroundand its count whole. A separator is 1 by 16 inBorder. Down the side the line list is at least 180 wide with a line of 1 inBorderat its start, a tab 32 high, padded 12, its label 13, and the selected tab marked with 2 inForegroundat its start. The pills are 30 high, padded 14, round, 4 apart, the label 13/500; the selected one isPrimarywith its label inPrimaryForeground. The panel is 16 under the list, or 24 beside it. - A tab follows the density by the steps of a row, 8 lower at compact, 8 and 12 higher at comfortable and touch, from the design’s height of each form: the default’s 28 is 20, 36 and 40; a line’s 44 (its list with it) is 36, 52 and 56, its 32 standing and its 40 overflowing (the bar and the list with it) the same steps; a pill’s 30 is 22, 38 and 42.
- The overflowing form is a row 40 high (over the line in the line variant): the list, its tabs 20 apart with labels of 13, between two scroll buttons 28 wide with chevrons of 14 in
Foreground, and More at the end, set apart by a line of 1 inBorder, padded 8 and 4, its label 13 and a chevron of 14 inMutedForeground. A scroll button moves the list most of the way it shows; it is for the pointer and no stop of Tab, since the arrow keys scroll the list to the tab they select. More opens a menu of every tab (ui::Menu), the selected one marked as a radio and a disabled one not to be chosen; choosing one selects it and scrolls the list the least that shows it. - A tab under the pointer has its label in
Foreground; a disabled tab is dimmed and does not light up. The focus ring is the tab’s; in the overflowing form it is drawn inside the tab, where the list that scrolls does not cut it off. - To what reads the tree (
lurq_snapshotof the MCP server) the list is atablistcalled bylabel, witha11y_orientation; a tab is atabcalled by its label, witha11y_selected(whichlurq_inspectreports asstate.selected); the panel atabpanelcalled by its tab. More hasa11y_haspopupmenuanda11y_expanded. - A renderer that draws other tabs has
view.tabs(each with its label, icon, count, and whether it is selected, disabled, set apart),view.part(part),view.tab_part(index, part),view.tab(index)(a tab with its behavior and its name to tooling),view.list()(the tabs as one focus group),view.separator(),view.panel()andview.bar()(the overflowing form). lurq::components::Tabsis another thing: a set of places of an app, each a router with a history of its own kept while it is not shown, with a bar to move between them across the bottom or the top. Tabs of the design system are a choice within a page.
In a narrow room. Tabs put in the tree with mount measure their room before a frame is painted: while the
list along the top is wider than it, they are their overflowing form (the list between two scroll buttons, More at
its end), scrolled to the selected tab, with no frame of the other form, and the list alone again when it fits.
overflow(true) keeps that form whether or not the list fits. Tabs converted into an element on their own cannot
measure: in a room too narrow they end their labels in an ellipsis, every tab still in the room. A theme’s renderer
gives the box that is the tabs’ room TabsView::room_ref. The form is the board’s Tabs/Overflow. Its tabs of a phone (Mobile/Scrollable Tabs: 48 high, labels of 15, scrolled with no buttons) are another dress of the same scrolling list, which an app gives with rules; the room does not choose it.
Accordion
Section titled “Accordion”Headers one under the other, each of which opens what is under it: questions and their answers, the sections of a long form, settings in groups. One item is open at a time, or any number.
use lurq::ui::{Accordion, AccordionItem};
// One open at a time, or none: open is a Signal<Option<u8>>, which a press sets.Accordion::optional(open, [ AccordionItem::text(0, "Is lurq GPU-accelerated?", "Yes. Rendering goes through wgpu."), AccordionItem::text(1, "Does it support dark mode?", "Every theme has two appearances."), AccordionItem::new(2, "Can I bring my own theme?", theme_form).disabled(locked),]);
// Any number open: sections is a Signal<Vec<&str>>. Each press is told the whole set open after it.Accordion::multiple(sections, [ AccordionItem::text("billing", "Billing", "Card, address and invoices."), AccordionItem::text("shipping", "Shipping", "Where the order goes."),]).on_change(|open: &[&str]| save(open));| Builder | |
|---|---|
Accordion::optional(Signal<Option<T>>, items) | One item open at a time: the one whose value the signal has, or none. A press of another opens it and closes the one that was open; a press of the open one closes it. An accordion has no form of which one must be open, so it has no plain new |
Accordion::multiple(Signal<Vec<T>>, items) | Any number open: those whose values the signal has. A press opens an item, or closes it |
Accordion::controlled_optional(Option<T>, items, on_change), Accordion::controlled_multiple(open, items, on_change) | The app holds what is open, one at a time or any number, and on_change is told what is to be open after a press of a header: the item or none, or the whole set. The accordion opens and closes nothing itself |
on_change(Fn(&Option<T>)), on_change(Fn(&[T])) | Told the accordion’s value after a press of a header, once the signal is set: the item open or none for one at a time (an Accordion<T>), every item open for any number (an Accordion<T, [T]>), checked by the compiler. Not what the app sets. A second one is called after the first |
label(&str) | What the accordion is called, to what reads the tree: a group of that name |
AccordionItem::new(value, label, content), AccordionItem::text(value, label, body) | An item: its value, what its header says, and what it shows while it is open, an element or a text. disabled(bool), id (its header’s) and key on an item |
disabled(bool), state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. disabled is every header’s; state is every item’s; force draws the header Tab stops on first, that of the first item that is not disabled |
- Each header is a stop of Tab, as a web accordion’s is, and Space and Enter press it; Up and Down move the focus from
one header to the next and round, Home and End to the first and the last. A disabled header is passed by, and so is
what an open item holds: a button in it is a stop of Tab between its header and the next, and the arrows are not the
accordion’s while the focus is on it (
FocusGroup::none()around the content). - What an item holds opens and closes with its height, over the theme’s base duration, and fades in and out with it: the panel’s height goes from none to its content’s, which the layout reads as it goes. Where motion is reduced it is there at once. While an item is closed what it held is not there: not painted, and the controls in it are no stops of Tab.
- Parts:
AccordionPart::Root(the items),Item(an item, with the line under it),Trigger(its header: what is pressed and focused),Label,Chevron,Panel(what opens and closes) andBody(what the panel holds, in its padding). Each item’s parts are styled in that item’s states,AccordionState::OpenandDisabled(AccordionStateisCollapsibleState). - In the design each item has a line of 1 in
Borderunder it. Its header is 14 above and under its label, which is - A header follows the density: 10, 18 and 20 above and under its label at compact, comfortable and touch, the steps of a row from the design’s 14.
in the body’s type (14) at medium weight in
Foreground, with a chevron of 16 inMutedForegroundat its end, 12 from the label: down while the item is closed, up while it is open. What it opens is in the body’s type inMutedForegroundat a line height of 1.5, 14 above the line. A disabled header is dimmed; the ring of the focus is around the header. - To what reads the tree (
lurq_snapshotof the MCP server) a header is abuttoncalled by its label, witha11y_expandedsaying whether its item is open. - A renderer that draws another accordion (
AccordionRenderer) is givenview.items, each aCollapsibleViewin the accordion’s recipe, andview.root(), the root with the behavior of the keyboard.
Collapsible
Section titled “Collapsible”One header and what it opens, with no others around it: the crates of a workspace, the details of an order, options a person rarely needs.
use lurq::ui::Collapsible;
// open: Signal<bool>, which a press of the header turns.Collapsible::new("3 crates in this workspace", crates).bind(open);
// The app holds whether it is open.Collapsible::text("Why is this here?", "Because the build needs it.") .open(shown) .on_open_change(move |next| show(next));| Builder | |
|---|---|
Collapsible::new(label, content), Collapsible::text(label, body) | A header that says label, and what it shows while it is open: an element or a text |
open(bool) | Whether what it holds is shown. The collapsible does not keep it: the app says so |
bind(Signal<bool>) | Open while the signal is true, which a press of the header turns; the handlers of on_open_change are told after it is set |
on_open_change(Fn(bool)) | Called on a press of the header with what the collapsible is to be: open if it was closed. Not for what the app sets. A second one is called after the first |
icon(..), open_icon(..) | The icon of the chevron by its name in the theme’s set, chevrons-vertical unless told otherwise, and the one while it is open, the same unless told otherwise. icon(None) takes the chevron away |
disabled(bool), state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. id is the id of the header |
- The whole header is pressed; Tab reaches it, and Space and Enter press it. What it holds opens and closes as an accordion’s item does.
- Parts:
CollapsiblePart::Root,Trigger,Label,Chevron,Panel,Body. States:CollapsibleState::Open,Disabled. - In the design the label is in the label’s type (13, medium),
Foreground; at the end of the header thechevrons-verticalicon of 16 is in a ghost button of 32 thatHighlightfills under the pointer; what it opens is 8 under the header. A disabled header is dimmed, and what it opens, which is the app’s, is not. - To what reads the tree the header is a
buttoncalled by its label, witha11y_expanded. - A renderer that draws another collapsible (
CollapsibleRenderer) starts fromview.trigger(), the behavior with the header’s style, andview.panel(), what opens and closes with what it holds;view.label()andview.chevron()(none where it has no icon) are the default ones.
Breadcrumb
Section titled “Breadcrumb”The way to where one is: a step for each place on it, each but the last a link back there, the last the page one is on. As a path control, the folders of a path in a bar, as a file manager has them.
use lurq::ui::{Breadcrumb, BreadcrumbSeparator, BreadcrumbStep, BreadcrumbVariant, icons};
Breadcrumb::new([ BreadcrumbStep::new("Settings").value("/settings"), BreadcrumbStep::new("Appearance").value("/settings/appearance"),]).step("Theme").on_select(|route| go_to(route));
// More steps than four: the first, an ellipsis that opens a menu of the hidden ones, and the last three. Mounted,// it keeps whether the menu is open.Breadcrumb::new([BreadcrumbStep::new("Home").icon(icons::HOME).value("/")]) .steps(["Projects", "lurq", "crates", "ui", "breadcrumb.rs"]) .max_shown(4) .separator(BreadcrumbSeparator::slash()) .mount(ctx);
// A path control: the parts of a path are its steps, each told as the path as far as it. Mounted, it folds the// middle of a path longer than its room into the menu of the ellipsis.Breadcrumb::path("H:\\projects\\lurq\\crates").on_select(|folder| open(folder)).mount(ctx);
// The same bar for steps of the app's own.Breadcrumb::new([ BreadcrumbStep::new("Macintosh HD").icon(icons::DRIVE).value("/"), BreadcrumbStep::new("projects").icon(icons::FOLDER).value("/projects"),]).variant(BreadcrumbVariant::Path);
// An edit form's trail, which ends with a link back to the task; a first step that is no page of the app.Breadcrumb::new([BreadcrumbStep::new("Tasks").value("/tasks"), BreadcrumbStep::new("KON-12").value("/tasks/KON-12")]) .current(false);Breadcrumb::new([BreadcrumbStep::new("~/projects/kon").link(false), "Settings".into(), "Upload".into()]);| Builder | |
|---|---|
new(steps) | A breadcrumb of these steps, in order. The last is the page one is on: text, not a link. A &str is a step of that label. Breadcrumb::default() has none |
current(bool) | Whether the last step is the page one is on: it is unless told otherwise. false ends the trail with a link like the steps before it (an editor’s form whose trail ends with the record it edits): it is followed, a stop of Tab, and gives way where the row is short as the page would, saying its whole name in a tooltip while it is cut. The same as BreadcrumbStep::link(true) on the last step |
step(impl Into<BreadcrumbStep>), steps(iter) | Steps, in order, after those it has |
Breadcrumb::path(&str) | A path control: the path of a folder or a file as a bar of its parts, the Path variant of BreadcrumbStep::path’s steps, called “Path”, which overflows. on_select is told the path as far as the part pressed |
BreadcrumbStep::path(&str) | The steps of a path, apart at / and \: a drive (H:, whose value is H:\), the root (/) or a share (\\nas\media) first, with the icon of a drive, a ~ with a home’s, the rest with a folder’s. A path to a file is given the file’s icon by the app, on the last step |
variant(..) | BreadcrumbVariant::Plain (the default: links in a line of text) or Path (segments in a bar, the last in a box of its own), or a variant the theme’s recipe names |
overflow(bool) | Mounted, the steps it has no room for go into the menu of the ellipsis, the ones nearest the first first, the first and the last never, and come back as it is given room. With max_shown too, no more than that many are shown where there is room for more. It does nothing to a breadcrumb that is not mounted: that one is its still form (see below) |
on_select(Fn(&str)) | Called with the value of the step followed, after the step’s own handlers |
tab_stop(bool) | false: Tab passes the links and the ellipsis by, and a press follows a link and leaves the focus where it was. See pointer-only pressables |
max_shown(usize) | The most steps shown. With more, the first, an ellipsis and the last max_shown - 1; never fewer than two. All of them without it |
link_max_width(length) | The most a link is wide (a number, or a Length): a longer name is cut there with an ellipsis, and a tooltip says it whole while it is cut (Tooltip::when_cut). The links keep their room, so the page one is on gives way first where the row is short. A rule of max_width on BreadcrumbPart::Link, and BreadcrumbView::cut_links. Mounted, the refs the tooltips read are kept from render to render |
mount(ctx) | Puts it where it goes, keeping whether the menu of the hidden steps is open and what it hangs from, and which steps one that overflows has no room for. Built on its own (build, .into()), its ellipsis opens nothing unless it is given menu, and it drops no step |
menu(Signal<bool>, ElementRef) | Whether the menu of the hidden steps is open, and what it hangs from, where the app keeps them, as for a menu. A press of the ellipsis turns it; choosing a step, a press outside and Escape close it |
label(&str), more_label(&str) | What the whole and the ellipsis are called to what reads the tree: “Breadcrumb” and “Show the hidden steps” unless told otherwise |
separator(BreadcrumbSeparator) | What stands between two steps: BreadcrumbSeparator::chevron() (the default), slash(), Icon(name) or Text(..) |
disabled(bool), state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. force draws the first link, the one Tab stops on first, in the state. The id is the prefix of the parts’ ids by the part-ids rule: the ellipsis x-ellipsis, the separators x-separator, x-separator-2, x-separator-3 in their order (a repeated part with no key is numbered from its second node, as in every component: there is no x-separator-1), a link and the page by their step’s value, which is their key (x-link-Home, x-page-Run 12); a step given its own id keeps it |
BreadcrumbStep::new(label) | A step. value(&str) is what on_select is told (its label until then), icon(name) an icon before its text, on_select(Fn()) called when it is followed, on_open_aside(handler) called for the middle button or a press with Ctrl (Cmd) on its link in place of following it (see pointer-only pressables), disabled(bool) dimmed and not followed (Tab passes it, and its item in the menu is disabled), link(bool) whether it is a link over what its place makes it (true on the last step ends the trail with a link; false on a step before it makes it plain text in the part Text: not followed, no stop of Tab, a disabled item in the menu; a place on the way that cannot be gone to), state(name, on) a state the theme’s recipe names for this step alone (a key in mono, a last step drawn as the steps before it: recipe.when(Selector::new().state("ancestor"), BreadcrumbPart::Page, ..)), id the id of its link, of the page, or of its item in the menu while it is hidden, key the key of its link |
- A link is followed by a click, and by Enter or Space while it is focused. The links and the ellipsis are stops of Tab in their order; the page is not. Choosing a hidden step in the menu follows it as a press of its link would.
- The page one is on, cut where the row is short, says its whole name in a tooltip that shows only while it is cut (
Tooltip::when_cut), in every breadcrumb, built or mounted; a link says its own while it is cut atlink_max_width. Mounted, the refs the tooltips read are kept from render to render. - Parts:
BreadcrumbPart::Root(the row),Link(a step that is a link: what is pressed, with its icon and text),Page(the last step),Text(a step that is neither:link(false), drawn as a link at rest, inMutedForeground, and as a segment in thePathvariant),Icon(a step’s icon),SeparatorandSeparatorIcon,Ellipsis(what is pressed to open the menu) andEllipsisIcon. States:BreadcrumbState::Collapsed(some steps are hidden),Disabled(of the whole, and of a step alone: it dims the link, the page, the separators and the ellipsis, so that a step can be dimmed by itself). A step’s own states (BreadcrumbStep::state) are on the parts of that step alone: its link or page and its icon. - In the design the steps are 8 apart in the body’s 14; the links are in
MutedForegroundand the page inForegroundat 500; a chevron of 14 inMutedForegroundstands between each two. The ellipsis is a square of 24 filled withHighlight(the board’s$accent), with the small radius and an icon of 16 inForeground. Under the pointer a link is inForeground; the ring of the focus is around the link. A step’s icon is 14, 4 before its text. A disabled breadcrumb is dimmed, follows nothing and is no stop of Tab. - The path control of the design (
Path Control) is thePathvariant: a bar 28 high onMutedwith the medium radius, 4 in from its sides, its segments touching. A segment is 22 high with the small radius, 6 in, an icon of 13 inMutedForeground5 before a text of 12 inForeground; a chevron of 12 inMutedForegroundstands between each two; the last, the folder one is in, is onBackgroundin an edge of 1 inBorder. The board draws no segment under the pointer and no ellipsis in the bar: a segment has theStateHoverandStatePressedveils, and the ellipsis is a square of 22 with an icon of 13. - In a room narrower than its steps a breadcrumb has two forms. The one that folds is
overflow(true)withmount(ctx): it measures before the frame is painted, so its first frame at a width is the settled one, and where even the first step, the ellipsis and the last have no room, the last is cut with an ellipsis. The still one is every other breadcrumb: one built on its own (build,.into()), withoverflowor without, and a mounted one withoutoverflow. It keeps nothing of what was measured, so it folds nothing: its root is no wider than its room, its last step gives way and is cut with an ellipsis, and the steps before it keep their widths, so that links wider together than the room run past its end. A breadcrumb in a window a person can narrow is the folding one; a still one is for a place that always has its room, or one that hides by count withmax_shown. - A theme gives the separator a renderer of its own with
set_part_renderer::<Breadcrumb, BreadcrumbPartRenderer>(BreadcrumbPart::Separator, ..), built once for each place between two steps; or restyles it by the recipe. - To what reads the tree (
lurq_snapshotof the MCP server) the root is anavigationcalled “Breadcrumb” (or itslabel), each link alinkcalled by its label, the page hasa11y_currentpage(a trail that ends with a link has none), a step that is no link is called by its label with no role, and the ellipsis, called “Show the hidden steps” (or itsmore_label), saysa11y_haspopupmenuand whether it isa11y_expanded. - A renderer that draws another breadcrumb has
view.shown()(the steps to lay out, by index: all but those overmax_shown;view.hiddenis what the ellipsis stands for, those a row dropped among them),view.step(index)(a link with its behavior, or the page),view.separator(),view.ellipsis()(the button with its menu, while some steps are hidden),view.root()andview.follow(index)(what following a step does).
Pagination
Section titled “Pagination”The pages of a list, one of them the current one: the results of a search, the rows of a table, the posts of a feed.
use lurq::ui::{Pagination, Select};
// Pages count from 1, as a person reads them. The signal has the current one, and a press sets it.Pagination::new(page.clone(), 20);
// The footer of a table: 284 rows, so many to a page, with a select of how many.Pagination::for_items(page.clone(), 284, size.get()) .compact(true) .page_size("Rows per page", Select::new(size.clone(), [(10, "10"), (20, "20"), (50, "50")]));
// The app holds the page: on_change is told the page of each press.Pagination::controlled(current, 12, move |to| go(to));| Builder | |
|---|---|
new(Signal<usize>, pages) | pages pages, of which the current one is the signal’s, counted from 1 |
for_items(Signal<usize>, total, page_size) | The pages of total items, page_size to a page |
controlled(current, pages, on_change) | The app holds the page: current, counted from 1, and on_change told the page of each press |
items(total, page_size) | The pages of so many items, in place of a number of pages; the compact form then says “1–20 of 284” |
siblings(usize) | How many pages are drawn on each side of the current one: 1 unless it is said |
compact(bool) | Previous and next with where the list is, and no pages |
page_size(label, Select) | A select of how many to a page, after its label, at the start; the pagination is then as wide as what holds it |
summary_text(&str) | What is said of where the list is, in place of “1–20 of 284” or “Page 3 of 12”: in another language |
previous_label(&str), next_label(&str), page_label(&str) | What previous and next are called, “Previous page” and “Next page”, and the word before a page’s number, “Page” of “Page 3”, unless told otherwise |
label(&str) | What the whole is called to what reads the tree: “Pagination” unless it is said |
on_change(handler) | Called with the page of each press |
disabled(bool), state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. force draws the first button that takes input (previous, or the first page that is not the current one) in the state. Its buttons have ids after the pagination’s: {id}-previous, {id}-next, {id}-page-3 |
- Which pages are drawn is the pagination’s: the first and the last always, the current one with its siblings on each side, and an ellipsis where pages are left out. While every page fits in
2 × siblings + 5every page is drawn; once they do not, that many things are drawn wherever the current page is, so that the row does not change its length as a person goes through it. Near an end the pages run on to that end and take the room of the ellipsis that is not needed there: on page 1 of 20,1 2 3 4 5 … 20; on page 10,1 … 9 10 11 … 20; on page 20,1 … 16 17 18 19 20. An ellipsis always stands for two pages or more.Pagination::pages_shown(current, pages, siblings)says what is drawn, asPageItem::Page(n)andPageItem::Ellipsis. - A current page past the ends is drawn as the end it is past; the signal is not changed. With no pages, previous and next are drawn, disabled, and nothing between them.
- Previous is disabled on the first page and next on the last. A press of a page goes to it; a press of the current one does nothing.
- Each page, previous and next is a button and a stop of Tab of its own; Left and Right move along the row (
FocusGroup::horizontal()), from the last on to the first, and Home and End go to its ends. Enter and Space press the button the focus is on. A disabled button is passed by, and one that is disabled while the focus is on it, as next is by Enter on the page before the last, passes the focus to the button before it: the keyboard stays in the pagination. - The page-size select is the app’s
ui::Select, bound to its own signal; the pagination gives its trigger the board’s size over the select’s recipe (PaginationPart::PageSize, laid overSelectPart::Trigger), and calls it by the label beside it. - To what reads the tree (
lurq_snapshotof the MCP server) the whole is anavigationcalled “Pagination” (or itslabel), each page a button called “Page 3” (after itspage_label), and the current one hasa11y_current“page”. Previous and next are called “Previous page” and “Next page” (or their labels). - Parts:
PaginationPart::Root,Nav(the row of buttons the arrow keys move along),Item(laid over each button’s root),Ellipsis,EllipsisIcon,Summary,PageSizeLabel,PageSize(laid over the select’s trigger). States:PaginationState::Compact,PageSize,Disabled, andCurrentof an item: the current page’s button. - In the design the pages are ghost buttons of 36, 4 apart, the current one an outline button; previous and next are ghost buttons of 36 with a chevron of 16. The ellipsis is a box of 36 with
more-horizontalof 16 inMutedForeground. A page button is at least 36 wide and 6 from its sides, so that a number of four digits or more still fits. The compact form has outline buttons of 30 for previous and next, 12 after where the list is, in the body’s type at 13 inForeground; its page-size select is 72 by 30 with its text at 13, 12 after its label inMutedForeground. A disabled button is dimmed as a button is. - A renderer is given a
PaginationView: where the list is (current,pages,shown,summary), andview.previous(),view.next(),view.page(n),view.ellipsis(i),view.summary(),view.nav()(the row of buttons) andview.page_size()(its label and the select) built in the recipe’s style with their behavior.
In a narrow room. A pagination put in the tree with mount reads its room before a frame is painted. Narrower
than its buttons, it draws fewer pages on each side of the current one, down to the first, the current and the last
between two ellipses; narrower than those, it says where the list is between previous and next (“Page 6 of 12”).
With room again it draws what the app says. Its root wraps: beside a select of how many to a page the pages go on
to a line under it, and a table’s footer puts its pagination under its count. The board draws no narrower form than
its compact one (Pagination/Compact, where the list is between previous and next), which is what the last step
is. A pagination that is only built (converted into an element, or build) cannot measure: it draws the pages the
app says in any room, and only its root wraps; mount(ctx) is the one that measures.
The stages of a process in order, with one current: those before it are done, those after it are to come.
use lurq::ui::{Orientation, Step, Steps};
// Shown, not operated: the app moves the current step itself. page: usize.Steps::at(page, ["Account", "Workspace", "Finish"]);
// A wizard that lets a person go back to a step that is done: a press sets the signal.Steps::new(at.clone(), [ Step::new("Account").description("Name and email"), Step::new("Billing").description("Card and address").invalid(billing_failed), Step::new("Finish"),]).orientation(Orientation::Vertical).label("Sign up").on_change(|index| println!("back to step {index}"));
// The current step held by the app, which answers a press itself.Steps::controlled(page, ["Account", "Finish"], move |index| go_to(index));| Builder | |
|---|---|
Steps::new(current, steps) | current is a Signal<usize> that holds the index of the current step, from 0, and that a press of a step sets. Past the last step every step is done. A step is a &str, a String or a Step |
Steps::controlled(current, steps, on_change) | The index held by the app: a press tells on_change, and the steps show what the app answers with |
Steps::at(current, steps) | The index of the current step, shown and not operated: the steps of a wizard the app drives. No step is pressed, whatever pressable and on_change say, and the steps are not a stop of Tab |
orientation(Orientation) | Horizontal (the default): in a row, a line between each step and the next. Vertical: in a column, a line down from each step’s mark to the next. StepsOrientation is a name of ui::Orientation |
on_change(Fn(usize)) | Called with the index of the step a person made current, after a signal given to new is set; not when the app sets it. Makes the steps that are done pressable. A second handler is called after the first |
pressable(bool) | Makes the steps that are done pressable with no handler: for steps bound to a signal |
ahead(bool) | Where steps are pressed, a step to come is pressed too: a process whose steps can be taken in any order |
label(&str) | What the list of steps is called to what reads the tree |
disabled(bool), state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. force draws the step Tab would enter at in the state. With an id, each step has the id <id>-<index>, its mark <id>-<index>-marker, and the line after it <id>-<index>-line |
Step::new(title) | A step. description(&str) a line under the title, icon(name) an icon of the theme’s set in place of its number until it is done, invalid(bool) that it has gone wrong, disabled(bool) that it takes no press and is dimmed, id the id of its element in place of <id>-<index>, key |
- In a row the steps share the width: where they do not fit, a step gives way before the lines, which are never shorter than 24. The descriptions wrap first, each step down to its title; only when every step is at its title is a title cut with an ellipsis, the last step’s first (
ShrinkLimit::ContentFirst). - Steps are read, not operated, unless the app says they are pressed (
on_change,controlledorpressable). Then a step that is done is pressed to go back to it, and a step to come only withahead(true); the current step and a disabled one change nothing. The steps are one stop of Tab, entered at the current step (at the last one pressed where every step is done); the arrow keys of the orientation, Home and End move between the current step and those that are pressed, and Space and Enter press. Steps that are only read take no press and no focus. - Parts:
StepsPart::Root(the steps and the lines),Step(a step: what is pressed and focused),Marker(its round mark),Number,Icon(the check, the cross, or the step’s own icon),Text(the title and the description),Title,Description,Rail(in a column, the mark with the line down from it),Connector(what holds a line) andLine. Each step’s parts are styled in that step’s states:StepsState::Done,CurrentorUpcoming, andInvalid,PressableandDisabled(that step alone); the whole hasDisabled. The orientation is the stateStepsState::HorizontalorVertical. - In the design the mark is 24 and round: in
Primarywith a check of 14 inPrimaryForegroundonce the step is done, inPrimarywith its number (12, medium) while it is current, and with a 1 px edge inInputand the number inMutedForegroundwhile it is to come. The title is 8 beside the mark in the label’s type (13, medium),Foreground, andMutedForegroundwhile the step is to come. A line of 1 runs from 12 after one step to 12 before the next, inPrimaryup to the current step and inBorderafter it; in a row the lines share what the steps leave of the width. A description is under the title in the caption’s 12,MutedForeground. An invalid step has a cross onDestructiveand its title inDestructive, whatever else it is. - A pressed step has a veil of
StateHoverunder the pointer and ofStatePressedheld down; the ring of the focus is around the step, which is padded 4 for it. Disabled steps are dimmed and take nothing. - To what reads the tree (
lurq_snapshotof the MCP server) the root is alist(called bylabel), each step alistitem, or abuttonwhere it is pressed, called by its place, title and state (“Step 2 of 4, Billing, current”, with ”, error” where it is invalid); the current step hasa11y_currentstep. - A renderer that draws other steps has
view.steps(each step with itsstatus, whether it ispressableand its resolved recipe),view.step_part(index, part),view.step(index, content)(a step with its behavior and its name to tooling),view.marker(index),view.text(index),view.connector(index)andview.step_name(index). A bar of segments, as the mobile skin draws progress, is such a renderer: aLineof each step, and the current step’s title under them.
In a narrow room. Steps across put in the tree with mount(ctx) measure their room before a frame is
painted. Their marks are always whole, and the titles end in an ellipsis first. Under the room the titles need
beside the marks, steps that are only read are the board’s progress of a phone (Mobile/Step Progress, the
progress state): a segment for each step, 4 high and 4 apart, in the primary color up to the current step, over
a line that says where the process is, “Step 2 of 4 · Billing” (parts segments, segment, summary). Steps a
person presses keep every step to press: the titles stand under their marks (the stacked state), and under the
room the marks and their lines need, the steps run down the page; the board draws neither of these two. Steps that
are only built (converted into an element, or build) cannot measure: they stay a row, keep their marks whole and
cut their titles.
Table of Contents
Section titled “Table of Contents”The list of a page’s sections, with the one being read marked: “On this page” beside an article, the outline of a document. It follows the scroll of the container the app names, and a press of an entry brings its section to the top.
use lurq::{core::ElementRef, ui::{TableOfContents, TableOfContentsEntry}};
// In `create`: a ref for each section, and one for what scrolls them.let (page, theme, palette, roles) = (ElementRef::new(), ElementRef::new(), ElementRef::new(), ElementRef::new());
// In `render`: each section has its ref on it (`.ref_element(theme.clone())`), the scroll has `page`.TableOfContents::new([("Runtime theme", &theme), ("Palette", &palette)]) .entry(TableOfContentsEntry::new("Extra roles", &roles).level(2)) .container(&page) .on_change(|index| println!("reading section {index}")) .mount(ctx);| Builder | |
|---|---|
TableOfContents::new(entries) | Its entries: TableOfContentsEntrys, or pairs of a label and the ref of a section |
entry(..), entries(..) | Adds to them |
mount(ctx) | The list where it is declared: it follows the scroll and goes to a section when its entry is pressed. Converted (.into()) it is still: see below |
container(&ElementRef) | What scrolls the sections, by the ref the app gave it: the reading line is measured from its top. With none, from the top of the window |
reading_line(impl Into<f32>) | How far under the top of the container a section’s top is when the section becomes the one read: 24 unless told |
current(Signal<usize>) | The entry marked, the app’s: the list sets it as the page scrolls and as an entry is pressed, and marks what the app sets. Without it a mounted list keeps the entry itself |
on_change(Fn(usize)) | Another section became the one read, by the scroll or by a press: after the signal is set, and not when the app sets it |
on_select(Fn(usize)) | An entry was pressed, before the list goes to its section |
title(&str) | What the list is called over its entries, in place of “On this page”; drawn in capitals. An empty one draws no title |
label(&str) | What it is called to tooling, in place of its title |
state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. force draws the marked entry |
| Entry | |
|---|---|
TableOfContentsEntry::new(&str, &ElementRef) | What the section is called, and the ref on the section’s element, or on its heading |
level(usize) | How deep the section is: 1 for a section of the page, 2 for a section of a section, which is set in |
disabled(bool) | It takes no input, and the keys pass it by |
id, key | Of the entry |
- A mounted list marks the last entry whose section’s top has come up to the reading line: at the top of a page the first, and each next one as its heading nears the top of the container. Where the container is scrolled to its end, with the last section all in view and the first gone up out of it, the last entry is marked, though its section’s top cannot come up to the line; scrolled back, the entry of the section at the line again. It adds observers of its own to the refs of its sections (
ElementRef::add_rect_observer_before_paint), so the entry is marked in the frame the scroll is drawn in, and an observer the app registered on one of those refs is kept; a new render replaces the list’s observers, which go with it. - A press of an entry scrolls its section to the start of what scrolls it (
ctx.scroll_into_view_start, clear of what sticks to the top), and marks the entry. A section near the end of the page cannot come up to the line, the page ends first: its entry is the marked one because it was pressed, until the page is scrolled again. - Converted into an element on its own it is the still form of itself: it marks what its signal says (the first entry with no signal), follows no scroll, and a press sets the signal and tells the handlers, and scrolls nothing. A list that is to stay in view while the page scrolls is in a container of the app’s that sticks (
.sticky(Sticky::top(0.0))). - To the keyboard it is one stop of Tab, at the marked entry. Up and Down move between the entries and do not wrap, Home and End go to the first and the last, Enter and Space go to the section; the focus stays on the entry. A label longer than the list is cut with an ellipsis on its one line.
- To what reads the tree it is a
navigation, called by its label or its title, oflinks called by their labels; the marked one says it is the current location (a11y_current). - Parts:
TableOfContentsPart::Root(the width, the room between the entries),Title,Entry(what is pressed: its height, the line at its start, the room before its label),Indent(its width is how far a level sets an entry in),Label. States, each an entry’s own:TableOfContentsState::Current,Disabled. - In the design (
i7m0J) it is 200 wide, its entries 2 apart under a title in the mono face at 11, in capitals a pixel apart, inMutedForeground, 12 in and 6 over the first entry. An entry is 28 high with a line of 1 inBorderat its start and its label 12 after it, 13 inMutedForeground; one of the second level is 12 further in. The marked one has a line of 2 inPrimaryand its label inForegroundat medium weight. The board draws no pointer: a label is inForegroundunder it, and the focus is a line of 2 in the ring’s color inside the entry. An entry is a row and follows the density. - A renderer that draws another list has
view.root(),view.title(),view.entry(index),view.entry_recipe(index)andview.render().
A short label of a state or a count, read and not operated: beta, passing, 3 unread.
use lurq::ui::{Badge, BadgeShape, BadgeSize, BadgeVariant, Button, icons};
Badge::new("Beta");Badge::new("Passing").variant(BadgeVariant::Success).icon(icons::CHECK);Badge::new("Online").variant(BadgeVariant::Success).dot(true);Badge::new("v0.60").variant(BadgeVariant::Secondary).shape(BadgeShape::Square);
// A dot alone: what it says is what it is called, not drawn.Badge::new("Unread").variant(BadgeVariant::Info).dot_only(true);
// A count: "99+" past 99, nothing at all at 0.Badge::count(unread).label("unread messages");
// On the top end corner of what it is about.Badge::count(3) .label("notifications") .on(Button::new("Notifications").icon(icons::BELL).icon_only(true));| Builder | |
|---|---|
Badge::new(label) | A badge that says label |
Badge::count(n) | A count: n in a small round badge, BadgeVariant::Destructive and BadgeSize::Sm unless told |
variant(BadgeVariant) | Default (the primary color), Secondary, Outline (an edge and no fill), and the statuses Info, Success, Warning, Destructive (the status’s muted fill and its strong text). A count in Destructive is solid |
size(BadgeSize) | Sm (18 high, at 11), Md (22, at 12, the default), Lg (26, at 13) |
shape(BadgeShape) | Pill (the default) or Square, with the theme’s small radius |
icon(name) | An icon of the theme’s set before the text |
dot(bool) | A dot in the variant’s color before the text; the badge then has an edge and no fill, as the design’s “Online” |
dot_only(bool) | A dot alone in the variant’s color. Its text is not drawn and is still what it is called |
max(usize) | The most a count shows: past it the maximum and a plus. 99 unless told |
show_zero(bool) | Whether a count of 0 is drawn. It is nothing unless told |
label(&str) | On a count, what it counts, which tooling is told with the number |
truncate(bool) | Gives way where it has less room than its word, down to its dot, its icon and its padding, the word ending in an ellipsis; what reads the tree is told the whole word. Off unless told: a badge keeps its width |
tooltip_when_cut(bool) | The whole word in a tooltip that shows only while the last layout cut it (Tooltip::when_cut): a badge that truncates in a narrow row. Not on a badge on an element. Off unless told |
word_ref(ElementRef) | Refers to the word’s text once it is laid out: text_cut() says whether it is cut, for a tooltip of the app’s own (Tooltip::when_cut(&word), with a hint while it is whole). tooltip_when_cut reads it where it is given |
on(element) | Puts the badge on the top end corner of element |
state(name, on), style(part, ..), rules(&recipe), id, key | As a button has them. id is the badge’s own, not the element’s it is on |
- A badge is read and not operated: it takes no press, no focus and no stop of Tab, and has nothing to force.
- On an element (
on), the badge and the element are one element as large as the element; the middle of the badge is on the point 3 in from the element’s top end corner, whatever the badge’s width, so a dot of 12 is at 27, -3 on a box of 36 (the design’s Indicator), a count of one digit reaches 6 past the corner each way, and a wider one as far to either side of the point. It has a ring of 2 inBackgroundthat parts it from what it is on. It reaches past the element, so what holds them gives it room or does not clip (overflow_visible()). A count that is not drawn leaves the element alone. - Parts:
BadgePart::Root(the badge: its fill, edge and height; a dot alone is its root),Label,Icon,Dot(the dot before the text),Anchor(what holds the element and the badge on it) andCorner(a square at the element’s top end corner whose centre the badge’s round end is centred on: its width is all that is read of it). States:BadgeState::Dot,DotOnly,Count,OnCorner,Square. The variant and the size are the recipe’s. - In the design a badge is 22 high and round, padded 8, its text 12/500 (the caption’s type at medium), an icon of 12 and 4 before the text; small is 18, padded 6, at 11 with an icon of 10; large is 26, padded 10, at 13 with an icon of 14. With a dot it is in
Backgroundwith a 1 px edge ofBorderand its text inForeground, the dot 7, 6 before the text, the badge padded 8 before and 10 after. A count is at 600 and at least as wide as it is high. A dot alone is 8 (6 small, 10 large), and 12 on a corner (10 small, 14 large). - To what reads the tree (
lurq_snapshotof the MCP server) a badge is astatuscalled by its text; a count is called by its number with what it counts (“120 unread messages”), the whole number however it is shown. - A renderer that draws another badge has
view.root()(the root with its style and its name to tooling),view.badge()(the default badge),view.text(what is drawn: “99+”),view.name(),view.shown(false for a count of 0 not drawn), andview.place(element, badge)withview.corner_offset()to put it onview.on.
Status Label
Section titled “Status Label”What a thing is doing, as an icon and a word in one tone, with no fill and no edge: the state of a run in a row of a table, of a step in a page’s header.
use lurq::ui::{StatusLabel, StatusLabelSize, StatusLabelVariant, icons};
StatusLabel::new("Completed").icon(icons::CHECK_CIRCLE).variant(StatusLabelVariant::Success);// Its icon turns while what it says is under way.StatusLabel::new("Running · 03 Implement").icon(icons::SPINNER).spin(true);StatusLabel::new("Queued").icon(icons::HOURGLASS).variant(StatusLabelVariant::Muted).size(StatusLabelSize::Sm);| Builder | |
|---|---|
StatusLabel::new(label) | A label that says label |
icon(name) | An icon of the theme’s set before the words |
spin(bool), spin_motion(SpinMotion) | The icon turns as a spinner does, by the theme’s spin motion or its own |
variant(StatusLabelVariant) | Neutral (Foreground, the default), Muted (MutedForeground), Info, Success, Warning, Destructive, or a tone the theme’s recipe names |
size(StatusLabelSize) | Md (an icon of 14, words of 12, 6 apart, the default) or Sm (12, 11, 4 apart) |
tooltip_when_cut(bool) | The whole words in a tooltip that shows only while the last layout cut them (Tooltip::when_cut): a status with a detail in a narrow row. Off unless told |
word_ref(ElementRef) | Refers to the words’ text once it is laid out: text_cut() says whether they are cut, for a tooltip of the app’s own. tooltip_when_cut reads it where it is given |
state(name, on), style(part, ..), rules(&recipe), id, key | As a badge has them. id is the root’s, with {id}-icon and {id}-label |
- A status label is read and not operated: no press, no focus, no stop of Tab. Its words are one line, cut with an ellipsis where its room is short; the icon keeps its size.
- Where a badge is a filled box, a status label has none: its words and its icon are in the tone’s strong color, at medium weight.
- Parts:
StatusLabelPart::Root(its color and the room between icon and words),Icon(its side),Label. States:StatusLabelState::Spinning. - To what reads the tree it is a
statuscalled by its words. A renderer gets aStatusLabelViewwithroot(),icon()(turning where it spins) andwords().
A label on a thing, a keyword or a category, that the app may let a person take away.
use lurq::ui::{Tag, TagShape, TagSize, TagVariant, icons};
Tag::new("design");Tag::new("in review").variant(TagVariant::Info).icon(icons::CIRCLE);
// With the button that takes it away: the app holds the list.Tag::new("rust").on_remove(move || topics.update(|all| all.retain(|t| t != "rust")));
// Round, with no line: the token of a box that holds several values.Tag::new("React").shape(TagShape::Pill).on_remove(move || remove("React"));
// A term and its value: the term before the label, as the app writes it.Tag::new("main").term("branch:").icon(icons::BRANCH);| Builder | |
|---|---|
variant(TagVariant) | Neutral (the default), Info, Success, Warning, Destructive, or a variant the theme’s recipe names |
size(TagSize) | Sm (20 high), Md (24, the default), Lg (28) |
icon(name) | An icon before the text, by its name in the theme’s set |
term(&str) | A term before the text, branch: before main, as the app writes it (its punctuation too), quieter than the text. The tag is still called by its text |
on_remove(handler) | Gives the tag its remove button, and is called on a press of it |
on_remove_event(Fn(&TagRemoveEvent)) | on_remove given what took the tag away: TagRemoveEvent::Press (the button’s press) or Key (Backspace or Delete on it). A tag in a row a press opens calls event.stop_propagation(), so the row hears nothing of it. Handlers of both are called in the order they were given |
shape(TagShape) | Default, or Pill: round at both ends, with no line around it |
remove_label(&str) | What the remove button is called to what reads the tree: “Remove” and the tag’s text by default |
disabled(bool) | Dimmed; its remove button is not pressed and Tab passes it by |
tab_stop(bool) | false: Tab passes the remove button by, and a press of it takes the tag away and leaves the focus where it was; focused by the app, Enter, Space, Backspace and Delete press it. See pointer-only pressables |
state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. id is the root’s; force draws the remove button |
- A tag does not keep whether it is there: the app holds its list, and
on_removetells it which one a person took away. A tag with no handler is read only: it has no button and is no stop of Tab. - The remove button is a button of its own, called “Remove” and the tag’s text (“Remove rust”) to what reads the tree, or its
remove_label; it has the tag’s id with-removeafter it. Tab reaches it, and a press, Enter, Space, Backspace and Delete press it; Backspace and Delete only while the focus is on it, with no modifier held. - Tags an app lays in a row with a focus group (
Row::new().focus_group(FocusGroup::horizontal())) keep the focus when one is taken away: it goes to the next tag’s button, or to the last, so Backspace takes them one after another. Outside a group the focus leaves with the button. - Parts:
TagPart::Root,Icon,Term(in the label’s type at regular weight,MutedForegroundon a neutral tag and the variant’s color on another),Label,Remove(the button),RemoveIcon(the cross: its side). States:TagState::Remove(it has the button),Pill,Disabled. - In the design a tag is 24 high, padded 8, with the corners of
RadiusSize::Sm, inSecondarywith a line ofBorderinside it, its text 12 and medium inSecondaryForeground. A removable one is padded 4 at its end, where a button of 16 (corners of 3) holds a cross of 11 inMutedForeground, 4 after the text; under the pointer the button is filledStateHoverand its cross isForeground. Focused from the keyboard, the button has a ring of 2 inRingaround its edge, which stands clear of the text before it.Info,Success,WarningandDestructiveare in the muted fill of their color, line and fill alike, with the text in the color. A pill is round, has no line, is padded 10 and 6, and its cross is 12. - Several tags side by side are an app’s row:
Row::new().spacing(6.0).wrap(), 6 apart as the board lays them out. - A renderer that draws another tag starts from
view.remove(), the button with its behavior and its cross,Nonefor a tag with no handler.
A tag that is pressed: a filter or a choice that is on or off. Open issues only, a language among others.
use lurq::ui::{Chip, ChipGroup, Choice};
Chip::new("Rust").selected(rust.get()).on_change(move |on| rust.set(on));// Bound to the app's signal: a press turns it.Chip::new("Open").bind(open);
// Any number chosen: the signal's values. One chosen: `ChipGroup::new(kind, [..])`.ChipGroup::multiple(languages, [ Choice::new("rust", "Rust"), Choice::new("swift", "Swift"), Choice::new("cobol", "Cobol").disabled(true),]);| Builder | |
|---|---|
selected(bool) | Whether it is chosen. The chip does not keep it: the app says so |
on_change(handler) | Called on a press with what the chip is to be: chosen if it was not |
bind(Signal<bool>) | Chosen while the signal is true, which a press turns |
icon(name) | An icon before the text while it is not chosen; a chosen chip has the check there |
disabled(bool), state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them |
ChipGroup | |
|---|---|
ChipGroup::new(signal, choices) | Exactly one chosen: the signal’s value. A press of another sets it |
ChipGroup::multiple(signal, choices) | Any number chosen: the signal’s values. A press adds a value or takes it out |
ChipGroup::controlled(value, choices, on_change) | The app holds the one chosen: a press of another tells on_change (Fn(&T)) the value it is to be, and a press of the chosen one tells nothing |
ChipGroup::controlled_multiple(values, choices, on_change) | The app holds those chosen: a press tells on_change (Fn(&[T])) the whole set it is to be |
on_change(handler) | Called as a person changes what is chosen, with the new value: &T for a group of one (a ChipGroup<T>), &[T] for one of any number (a ChipGroup<T, [T]>), checked by the compiler. Not called where the app sets the signal. Each one adds |
label(&str) | What the group is called to what reads the tree, a group; a field’s label where it has none |
invalid(bool) | Each chip has a line in the destructive color; a field’s judgment sets it. State: ChipGroupState::Invalid |
disabled(bool), state(name, on), style(part, ..), rules(&recipe), force(..), id, key | ChipGroupPart::Item lays rules over each chip’s root. force draws the chip Tab stops on |
- Tab reaches a chip, Space and Enter turn it, and the focus ring is the chip’s. A group is one stop of Tab: the arrow keys move between its chips and Space or Enter turns the one the focus is on. A choice is a
Choice, as a toggle group’s: its icon is the chip’s. - To what reads the tree a chip is a
buttoncalled by its text, witha11y_pressedsaying whether it is chosen;lurq_inspectreports it asstate.pressed. - Parts:
ChipPart::Root(what is pressed),Icon,Label;ChipGroupPart::Root,Item. States:ChipState::Selected,Icon(it has an icon before its text: the check or its own),Disabled. - In the design a chip is 28 high and round, padded 12, its text 13 and medium. One not chosen is in
Backgroundwith a line ofInputand its text inForeground,Highlightunder the pointer; a chosen one is inPrimary, line and fill, its text inPrimaryForeground, with a check of 14 before it, 6 from it and padded 8 at its start, and inPrimaryHoverunder the pointer. A disabled chip is dimmed. The chips of a group are 6 apart and go on to the next line where the row has no room. - A renderer that draws another chip starts from
view.root(), the behavior with the root’s style;view.shown_icon()is the icon the default renderer puts before the text.
Avatar
Section titled “Avatar”Who a person is, at a glance: the initials of the name on a fill, a picture in their place, whether the person is there.
use lurq::{components::Image, ui::{Avatar, AvatarPresence, AvatarShape, AvatarSize, icons}};
Avatar::new("Ivan Zaida");Avatar::new("Ivan Zaida").image(Image::from_file("ivan.png")).presence(AvatarPresence::Online);Avatar::new("Ivy Chen").size(AvatarSize::Xl);// The app's letters; tooling still calls it "Ada King Lovelace".Avatar::new("Ada King Lovelace").initials("AK");
// What is not a person: an icon in place of the initials, in a square.Avatar::new("Build bot").icon(icons::TERMINAL).shape(AvatarShape::Square);| Builder | |
|---|---|
new(&str) | Who it is. The initials are the first letters of the first word and the last: “Ivan Zaida” is “IZ”, “Ivan” is “I”. A name with no letters shows the icon of a person |
initials(&str) | The letters the face shows, in place of those taken from the name: the app’s own way of making them. The name stays what tooling calls the avatar. Empty letters show the icon of a person |
image(Image) | A picture in place of the initials, which fills the face, cropped to it (cover) and clipped to its shape: the engine’s image element as the app builds it, from pixels (Image::new) or from a file or bytes it decodes (Image::from_file, Image::from_bytes, feature image), with a cache key and a size to decode to where it wants them. Feature raster |
icon(IconChoice) | An icon of the theme’s set in place of the initials, for what is not a person: a bot, a team. None is no icon, not even the person a name with no letters shows |
size(AvatarSize) | Xs 20, Sm 24, Md 32 (the default), Lg 40, Xl 56, or a size the theme’s recipe names |
shape(AvatarShape) | Circle (the default), or Square with the corners of a control |
presence(AvatarPresence) | The dot at the bottom end of the face: Online, Away, Busy, Offline; None for none |
presence_label(&str) | What the dot says to tooling after the name, in place of the presence’s own word: the app’s word, or the word in another language |
state(name, on), style(part, ..), rules(&recipe), id, key | As a button has them. id is the root’s |
- While a picture decodes and when it fails (a broken file, a format the decoder does not read), the avatar shows its initials or its icon: they are the image’s placeholder and its error view. A picture with clear pixels shows the face’s fill through them.
- An avatar is read, not operated: it takes no press and is no stop of Tab. To what reads the tree (
lurq_snapshotof the MCP server) it is animgcalled by its name, with its presence after it: “Ivan Zaida, away”. - Parts:
AvatarPart::Root(the face and the dot, as large as the face),Face(the shape: side, corners, fill, the ring of a group; it clips what it holds),Initials,Icon(its width is the icon’s side),Image,Presence(the dot). States:AvatarState::Square, and the avatar’sAvatarPresenceunder its own name (.state(AvatarPresence::Away, AvatarPart::Presence, ..)). Sizes:AvatarSize. - In the design an avatar is a circle of 32 in
Muted, its initials 12 and medium inForeground; at 20, 24, 40 and 56 they are 9, 10, 14 and 18. A square one has the corners ofRadiusSize::Md. The icon is half the side, inMutedForeground. The dot is 10 on a face of 32 (6, 8, 12 and 14 on the others), at the face’s bottom end corner, round, ringed 2 outside it inBackground:Successonline,Warningaway,Destructivebusy,MutedForegroundoffline. - The ring of the dot stands outside the avatar’s box, as the rings of a group do: what holds an avatar at its edge clips them, as a container clips what is in it, unless it leaves 2 of room or is
overflow_visible(). - The dot on its own, with no avatar under it, is
Presence::new(AvatarPresence::Online): before a word in a list of who is there, beside a name in a line of text. It is theAvatarPart::Presenceof the avatar’s recipe, in the color of its presence and at the side of the dot of an avatar of itssize(AvatarSize)(10 unless told), so a theme that restyles an avatar’s dot restyles it; it has no ring, with no face to part it from.styleandrulesname the avatar’s parts, andlabel(&str)says what tooling calls it in place of the presence’s word: it is animgcalled “online”. - A person with a name and a line under it (the board’s Persona) is a persona.
- A renderer that draws another avatar has
view.face()(the shape in its style, clipped),view.fallback()(the initials or the icon),view.presence_dot()andview.label();view.imageis the picture the app gave, to put in the face.
Avatar group
Section titled “Avatar group”Avatars laid over one another: who is in a document, who reviews a change.
use lurq::{ app::theme::PaletteColor, node::border::Border, ui::{Avatar, AvatarGroup, AvatarGroupPart, AvatarSize},};
let people = ["Ivan Zaida", "Anna K.", "Mark R.", "Ivy Chen", "Ivo Kovac", "Lena Quinn"];// Three, and "+3" for the three it leaves out.AvatarGroup::new(people.map(Avatar::new)).max_shown(3).label("Reviewers");
// On a card, the ring is the card's color.AvatarGroup::new(people.map(Avatar::new)) .size(AvatarSize::Sm) .style(AvatarGroupPart::Item, |s| s.border(Border::outside(2.0, PaletteColor::Card)));| Builder | |
|---|---|
new(avatars) | The avatars, in order: each lies over the end of the one before it |
max_shown(usize) | The most avatars it shows; after them a last one says how many it leaves out, “+3” |
size(AvatarGroupSize) | The size of every avatar in it: an AvatarSize |
label(&str) | What it is called to what reads the tree. Without one, the names it shows and how many more |
state(name, on), style(part, ..), rules(&recipe), id, key | As a button has them |
- The group gives its avatars its size and what its recipe says of an item; each keeps everything else it was given: its picture, its icon, its presence.
- To what reads the tree it is a
groupcalled by its label; the count is animgcalled “3 more”. - Parts:
AvatarGroupPart::Root(the row: how far each avatar lies over the one before, as a gap below nothing),Item(laid over each avatar’sFace: its ring),More(laid over the count’sFace, afterItem). Sizes:AvatarSize. - In the design avatars of 32 lie 8 over one another, each ringed 2 outside its face in
Background, the color of the surface behind them; the count is inSecondary, its text as the initials. Smaller and larger avatars lie a quarter of their side over each other. - A renderer that draws another group has
view.avatars(ready, with the group’s size and rules),view.hiddenandview.more(), the count as an avatar.
Persona
Section titled “Persona”A person in a list, a menu or a header: their avatar with the dot that says whether they are there, their name, and a line under it.
use lurq::ui::{Avatar, AvatarPresence, AvatarShape, Persona, PersonaSize, icons};
Persona::new("Ivan Zaida").description("Available · Kyiv").presence(AvatarPresence::Online);Persona::new("Ivy Chen").description("Away · back at 15:00").presence(AvatarPresence::Away).size(PersonaSize::Lg);
// An avatar of the app's own: a picture, an icon, a shape.Persona::new("Build bot") .description("Runs on every push") .avatar(Avatar::new("Build bot").icon(icons::TERMINAL).shape(AvatarShape::Square));| Builder | |
|---|---|
new(&str) | Who it is: the name beside the avatar, and the avatar’s initials |
description(&str) | The line under the name, in the muted color |
presence(AvatarPresence) | The dot at the corner of the avatar; None leaves the avatar as it was given |
presence_label(&str) | What the dot says to tooling in place of the presence’s own word, as an avatar’s |
avatar(Avatar) | An avatar in place of the one the name gives, with a picture, an icon or a shape of its own. The persona gives it its size, and its presence where it has one |
size(PersonaSize) | The avatar’s: Xs 20, Sm 24, Md 32 (the default), Lg 40, Xl 56, with the text to match. PersonaSize is AvatarSize |
state(name, on), style(part, ..), rules(&recipe), id, key | As a button has them. id is the root’s |
- A name or a description longer than the room there is ends in an ellipsis, each on its one line; the avatar keeps its size, and the persona is no wider than what holds it.
- A persona is read, not operated: it takes no press and is no stop of Tab. To what reads the tree it is a
groupcalled by the name and described by the description, with its avatar, animg, in it. - Parts:
PersonaPart::Root(the avatar and the text, side by side),Avatar(what the persona says of its avatar’s face, laid over the theme’s recipe for it),Text(the name over the description),Name,Description. State:PersonaState::Description(it has the line). Sizes:PersonaSize. - In the design a persona is an avatar of 32, 10 before a name in 14 and medium in
Foregroundwith a line 1 under it in 12 ofMutedForeground. The board draws that one size; the others follow the avatar’s: at 20 and 24 the name is 12 and 13 over a line of 11, 6 and 8 from the avatar; at 40 and 56 it is 15 and 18 over a line of 13 and 14, 12 and 14 from it. - The ring of the avatar’s dot stands outside the persona’s box: what holds a persona at its edge leaves 2 of room or is
overflow_visible(), as with an avatar. - A renderer that draws another persona has
view.root(),view.text()andview.avatar, the avatar with the persona’s size and presence, to build where it likes.
A surface that holds one thing: a group of settings, a summary of a project, a form of a few fields.
use lurq::{ components::Text, layout::Alignment, node::padding::Padding, ui::{Button, ButtonVariant, Card, CardSize, CardVariant},};
Card::new() .title("Appearance") .description("How lurq looks on this device.") .child(accent_field) .child(dark_mode_row) .footer(Button::new("Cancel").variant(ButtonVariant::Outline)) .footer(Button::new("Save"));
// Pressed as a whole: one stop of Tab.Card::new() .variant(CardVariant::Elevated) .size(CardSize::Sm) .title("lurq") .description("A Rust UI toolkit with GPU-backed rendering.") .on_click(move |_| open_project());
// Laid out as a column is, from its own builder.Card::new() .padding(Padding::symmetric(16.0, 12.0)) .gap(4.0) .align_items(Alignment::Center) .flex(1.0) .child(Text::new("1,284")) .child(Text::new("Runs this week"));| Builder | |
|---|---|
title(&str) | What the card is about, 16/600. It is what the card is called unless it has a label, and wraps in the width the card has |
label(&str) | What the card is called to what reads the tree, in place of its title |
description(&str) | More of it, under the title, 14 in the muted color |
action(element) | At the end of the header, beside the title: a button, a menu, a badge. A card has one: a second call takes its place |
child(element), children(..) | Add to the body, under the header |
footer(element) | Added to a row at the end of the card, under a line: its least action first and its main one last |
variant(..) | CardVariant::Outline (the default), Elevated, Filled, or a variant the theme’s recipe names |
size(..) | CardSize::Md (the default) or Sm, or a size the theme’s recipe names |
width(..) | A width of its own. Without one the card is as wide as the room it is given |
height(..), min_width(..), max_width(..), min_height(..), max_height(..) | A height of its own, and the least and the most it is wide and high: a number or another Length |
padding(..) | The room inside it around its header and its body, in place of its size’s: a Padding, a number, or a step of the theme’s spacing. The footer keeps its own |
gap(..) | The room between its children, and between its header and its body, in place of its size’s |
align_items(Alignment) | How its children are aligned across its width, as a column aligns them |
flex(f32), flex_shrink(f32) | Its share of the room left in a row or a column, and how much of its size it gives up where there is too little |
absolute(x, y, width, height) | Where it stands in the Stack that holds it |
describe(name, value) | What its surface says to tooling, beside its role and its name: the state of what it shows |
on_click(handler) | Makes the card pressed as a whole, from the pointer and the keyboard |
disabled(bool), state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. id is the id of the surface |
- Every part is optional: a card with children alone is a padded surface. The header is there where the card has a title, a description or an action; the footer where it has something in it, set off by a line only where there is content over it.
- A card is as wide as the room it is given, as a block is. Cards side by side in a row are each given a share of it:
flex(1.0)on each, or a grid. The title and the description wrap in the room the action leaves them. - A card given a height of its own (
height, or its recipe’s onCardPart::Root) gives what its header leaves to its body, so the body’s children withflex(1.0)fill it (figure cards of one height in a row, eachheight(118.0).flex(1.0)), and its footer stays at the bottom. A card as high as what is in it, or given only a least height, gives nothing: a column that grows in lurq’s layout takes all the room it may. A card that is a share of a column takesheight(Length::Fill).view.has_height()tells a renderer. - What is in a card is clipped to its rounded corners, as what is in any element is to its own box: a table or a picture that reaches the card’s edge does not paint over its corners. A control flush with the edge has its focus ring clipped there too, so content keeps its padding or is
overflow_visible(). - A card is laid out as a column is, from its own builder, though what it holds is two levels down: what lays out what is in it goes to its content and its body (
paddingto the content,gapto the content and the body,align_itemsto the body), and what places it in what holds it goes to its surface (width,heightand their least and most,flex,flex_shrink,absolute,describe), on a read card and a pressed one alike. The padding, the gap and the sizes are rules of the card over the theme’s recipe, so a renderer finds them inview.part(..); the alignment, the flex, the place and what it describes are laid on the node thatview.body(),view.read_root()andview.pressed_root()give. - A card given
on_clickis pressed as a whole: one stop of Tab, with the focus ring around it, pressed by a click, Enter and Space. The controls in its action and its footer are stops of Tab of their own, after the card, and a press of one of them is that control’s and not the card’s; a control in its body is pressed with the card, so a pressed card keeps its controls in the action and the footer. A card withouton_clickis read: it is no stop of Tab, and each control in it is a stop of its own. - Parts:
CardPart::Root(the surface; what is pressed),Content(the header over the body, padded),Header(the text and the action),Text(the title over the description),Title,Description,Action,Body(what the app put in it),Footer. States:CardState::Pressable,Disabled,Footer(it has a footer under its content; the line over the footer is the content’sunderline). - In the design a card is in
CardwithCardForegroundink and corners ofradius-xl. The outlined card has an edge of 1 inBorderand the small shadow, the elevated one the medium shadow and no edge, the filled oneMutedand no edge. Its content is padded 24 with 24 between the header and the body; the title is 16/600, the description 6 under it in 14 ofMutedForeground; what is in the body is 16 apart; the footer is padded 16 and 24 with its buttons 8 apart at its end. A small card is padded 16, with a title of 14 and a description of 13. A pressed card takes an edge ofRingand the medium shadow under the pointer, and the small shadow again while it is held down; a disabled one is dimmed. - A surface of the app’s own is a card with its parts styled:
style(CardPart::Content, |s| s.padding_x(14.0).padding_y(14.0)),style(CardPart::Root, |s| s.radius(RadiusSize::Lg).shadow(BoxShadowValue::none())), and what it holds as the body. The settings card and the stat card of the design are components of their own: a settings card and a stat card. - To what reads the tree (
lurq_snapshotof the MCP server) a card is agroupcalled by its label or its title, and a pressed card abutton. - A renderer that draws another card (
CardRenderer) starts fromview.read_root()orview.pressed_root(), the surface with its behavior, and puts in it what it likes:view.content()(the header over the body),view.header(),view.text(),view.action(),view.body()andview.footer()are the default ones.
Expandable Tile
Section titled “Expandable Tile”A tile that is pressed to show more of itself: a fact with its details, a figure with where it comes from, a plan with what it includes.
use lurq::{components::Text, core::Signal, ui::{ExpandableTile, icons}};
// The board's tile, open.ExpandableTile::text("Renderer", "wgpu 26 on DirectX 12. Frame time 6.9 ms median.").open(true);
// Open while the signal is true, which a press of the tile turns.let open = Signal::new(false);ExpandableTile::text("Renderer", "wgpu 26 on DirectX 12.") .bind(open.clone()) .on_open_change(|open| println!("open: {open}"));
// What it always shows, over an element it opens.ExpandableTile::new("Team", Text::new("Unlimited seats, SSO, audit log.")) .child(Text::new("$12 a seat")) .icon(icons::PLUS) .open_icon(icons::MINUS);| Builder | |
|---|---|
ExpandableTile::new(title, element) | Its title, and what it shows while it is open |
ExpandableTile::text(title, text) | Its title, and a text it shows while it is open, in the detail’s type |
child(..), children(..) | What it always shows, under its header: a figure, a line, a chart |
open(bool) | Whether what it opens is shown |
bind(Signal<bool>) | Open while the signal is true; a press turns it |
on_open_change(Fn(bool)) | Told of a press, with what the tile is to be: after the signal is set where it is bound, and not when the app sets it |
icon(..), open_icon(..) | The icon of the chevron (chevron-down), and of the open tile’s (chevron-up, or its icon where it was given one); None for no chevron |
disabled(bool) | It takes no input |
full_width(bool) | As wide as what holds it, in place of the design’s 260 |
label(&str) | What it is called to tooling, in place of its title |
state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them |
- The whole tile is pressed: by the pointer anywhere on it, and by Enter and Space once Tab has reached it. It does not keep whether it is open: the app says so (
open), or binds it (bind). With neither a handler nor a signal a press does nothing. - A press of an element the app put in it (what
childgave it, the element it opens) is that element’s alone, and the controls in it are stops of Tab of their own, after the tile. A press of the text ofExpandableTile::textis the tile’s. - What it opens opens and closes with its height over the theme’s base duration and fades, as a collapsible’s does, at once where motion is reduced. While it is closed it is not there: the controls in it are not stops of Tab.
- A long title goes on to the next line, and the chevron stays at the end of its first.
- To what reads the tree it is a
button, called by its label or its title, which says whether what it opens is open (a11y_expanded). - Parts:
ExpandableTilePart::Root(what is pressed: the fill, the edge, the padding),Header,Title,Chevron,Body(what it always shows),Panel(what opens: its height),Detail(what the panel holds, and the type of its text). States:ExpandableTileState::Open,Disabled,FullWidth,Body. - In the design (
slE1t) it is 260 wide onBackgroundin an edge of 1 inBorderwith the large radius, padded 16; its title is 14 at medium weight, 8 before a chevron of 16 inMutedForeground; what it opens is 10 under the header, a text of 13 on lines of 1.5 inMutedForeground. The board draws it open and at rest: closed it haschevron-down, under the pointer its edge is in the ring’s color, as a pressed card’s is, the focus is the theme’s ring around it, and what it always shows is 10 under its header. - A renderer that draws another tile has
view.root(),view.header(),view.title(),view.chevron(),view.body(),view.panel()andview.render().
Scroll Area
Section titled “Scroll Area”Content that scrolls in a room of its own: a dialog’s long body, a list in a panel, a table’s cells. Its bar is the design’s.
use lurq::ui::{ScrollArea, ScrollAreaOrientation, ScrollAreaScrollbars};
ScrollArea::new() .height(184.0) .label("Terms of use") .children(paragraphs);
// A list with its bar in a lane of its own beside the rows.ScrollArea::new().width(340.0).height(160.0).gutter(true).children(rows);
// A table's cells, both ways, the bars only under the pointer and while they scroll.ScrollArea::new() .orientation(ScrollAreaOrientation::Both) .scrollbars(ScrollAreaScrollbars::Hover) .child(cells);| Builder | |
|---|---|
ScrollArea::new(), child(element), children(..) | What scrolls: one under another, or side by side in an area that scrolls across |
orientation(..) | ScrollAreaOrientation::Vertical (the default), Horizontal, or Both; a ui::Orientation is one of the first two |
scrollbars(ScrollAreaScrollbars) | When its bars show: Auto (while the content overflows), Always, Hover (under the pointer and while it scrolls, then they fade), Scrolling (only while it scrolls, as a system set to show scroll bars only when scrolling), Never |
gutter(bool) | Its bars in a lane of their own beside the content, kept while a bar fades, and not over its edge |
fill_width(bool) | What scrolls across is at least as wide as the area: items that grow share the room there is, and it scrolls sideways only once they need more (a timeline across) |
label(&str) | A region of that name to what reads the tree, and a stop of Tab whose keys scroll it |
scroll_state(ScrollState) | The app’s: where it is scrolled to, read and set |
width(..), height(..), max_height(..) | Its size, impl Into<Length>; it is as large as the room it is given without one |
state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them; force draws its ring of focus |
- Its content scrolls with the wheel (smoothly, as every scroll container’s), a finger, a drag of the bar’s thumb and a press on its track. A bar is drawn over the content’s edge unless the area has a
gutter; content that runs under it, as a text does, is given a padding of the root at its end. - A scroll area with a label is a stop of Tab with the ring of the focus inside it. With the focus on it, Up and Down scroll it by 40, Left and Right likewise across, PageUp, PageDown, Space and Shift+Space by what it shows, Home and End to its ends: the keys of any scroll container that has the focus itself. Give a label to an area whose content has nothing that takes the focus, so that the keyboard reaches it. One with no label is no stop: the controls in it are.
- To what reads the tree it is a
regioncalled by its label, and each bar of content that overflows is a scrollbar with its value:scrollbar_verticalandscrollbar_horizontal, how far it is scrolled from 0 at its start to 100 at its end. - Its bar is the theme’s
ScrollBarStyle(theme.scrollbar()), shown and placed as the area says: the scroll area adds no look of its own to the bar, and a theme that changes the bar changes it here and on every scroll container. - In the design (
Scrollbar) the bar is a lane of 8 with no fill, padded 1, and a thumb of 6 in it, round, inRing. Under the pointer, and while it is dragged, the thumb isMutedForeground. The lane is 2 from the edge it runs along and from the ends of the area. The board has the bar beside a list’s rows and in a dialog’s padding; it draws no bar across, no corner where two meet, and no bar under the pointer or dragged, which are the engine’s with the board’s numbers: where both bars are there, each ends before the other’s lane, and the corner is no bar’s. - Parts:
ScrollAreaPart::Root. States:ScrollAreaState::VerticalandHorizontal(both on for an area that scrolls both ways),Gutter. - A renderer that draws another area has
view.content(), what scrolls laid out its way,view.bar, the theme’s bar as the area shows it, andview.render().
Content that gives way first. ScrollHorizontal::fit_width(true) lays content wider than the viewport out
in the viewport’s width first, so that a line gives way there by its own rules (its children shrink, or drop out
of it), and scrolls only to what still has no room: a toolbar’s controls go into its menu as it narrows, and the
bar scrolls to the ones that stay.
Separator
Section titled “Separator”A line between things: sections of a page, groups of a toolbar, the two ways to sign in.
use lurq::ui::Separator;
Column::new() .child(github_button) .child(Separator::horizontal().label("or")) .child(email_button);
// Down a row that centers what is in it: a length of its own.Row::new() .align_items(Alignment::Center) .child(undo) .child(Separator::vertical().length(20.0)) .child(bold);| Builder | |
|---|---|
Separator::new(), horizontal(), vertical() | A line across a column (new and horizontal), or down a row |
orientation(Orientation) | Which way it runs: Horizontal (unless told) or Vertical. SeparatorOrientation is ui::Orientation |
label(&str) | A word in the middle, with the line on either side of it |
length(f32) | How long it is: its width across a column, its height down a row |
decorative(bool) | Whether tooling passes it by. On by default |
state(name, on), style(part, ..), rules(&recipe), id, key | As a button has them |
- A label longer than the room is cut with an ellipsis on one line, and a line of 24 at least stays on either side of it.
- A separator across a column is as wide as the room it is given. One down a row is as high as the row where the row stretches its children (
align_items(Alignment::Stretch)); in a row that does not, it is given alength. An inset is the root’s padding:style(SeparatorPart::Root, |s| s.padding_x(16.0)). - Parts:
SeparatorPart::Root(the line, or the lines and the label),Line,Label. States:SeparatorState::HorizontalandVertical, one of them on, which a recipe styles each way by. - In the design the line is 1 in
Border. A label is in the caption’s type inMutedForeground, 8 from the line on either side. - A separator is decoration to what reads the tree. One given
decorative(false)is aseparatorwitha11y_orientation, called by its label where it has one: for one between parts a person moves between. - Tabs, the dialog and the menu draw lines of their own from their recipes.
Spinner
Section titled “Spinner”Something is being done, and how far it is is not known: a ring that turns, three dots or five bars.
use lurq::ui::{LoadingOverlay, Spinner, SpinnerKind, SpinnerSize};
Spinner::new();Spinner::new().size(SpinnerSize::Lg).kind(SpinnerKind::Dots);// Beside the text that says what is being done.Spinner::new().label("Loading results…");
// A veil with a spinner over a part of the page while it loads.LoadingOverlay::new(loading.get(), panel);
// In the place of a whole page while it starts.PageLoader::new("Starting lurq").description("Loading your workspace…");| Builder | |
|---|---|
kind(SpinnerKind) | Ring (the default), Dots or Bars |
size(name) | SpinnerSize::Sm (16, the default), Md (24), Lg (32); the dots and the bars grow by a half and by twice |
variant(name) | SpinnerVariant::Current (the color of the text around it, dots and bars too), Muted, Primary |
label(&str) | What is being done, drawn 8 beside it, and what it is called |
label_hidden(bool) | The label is its name and is not drawn |
decorative(bool) | No status of its own, where what it is in says what is under way: a button that loads |
motion(SpinMotion) | How the ring, the dots or the bars move, in place of the theme’s: in steps, and still where motion is reduced |
state(name, on), style(part, ..), rules(&recipe), id, key | As a button has them |
- To what reads the tree a spinner is a
status, called by its label, or “Loading” when it has none. - The ring is the glyph a button turns while it loads, and
Button::loadingdraws aSpinner: a rule a theme lays over the spinner reaches the button’s. It turns withui::SPINonce inSPIN_PERIOD. The dots fade one after another withui::SPINNER_DOTS, the bars shrink about their middle one after another withui::SPINNER_BARS; all of them play on the animation clock, so every spinner on screen moves as one. A spinner moves whether or not motion is reduced, unless its motion says to stand still: one that stood still would say nothing. - A spinner is drawn in the color of the text around it, so a spinner in a button is the color of its label: the ring as text is, and the dots and the bars by the fill
BackgroundColor::CurrentForeground. Where nothing around it names a color, that isForeground. A variant gives it a color of its own. - Parts:
SpinnerPart::Root(the spinner and its label),Indicator(the ring as a square of its side, or the row of the dots or of the bars),Dot,Bar,Label. States:SpinnerState::Dots,Bars. - In the design the ring is 16, 24 or 32; the dots are 8, 6 apart, in a row 16 high, at 1, 0.6 and 0.3 of their color at rest; the bars are 3 wide and round, 3 apart, 8, 18, 12, 20 and 10 high in a row of 20; the label is 13 in
MutedForeground. LoadingOverlay::new(loading, content)lays a veil overcontentwhileloadingis true: the background’s color at 85 hundredths, with a spinner in its middle (.spinner(Spinner)gives one of the app’s). Meanwhile no press reaches the content and Tab passes it by. The veil fades in withui::FADE_INand out withui::FADE_OUTover the theme’s base duration. The overlay is as large as its content; its root clips the veil, so a rule that roundsLoadingOverlayPart::Rootrounds the veil with a rounded content. Parts:Root,Content,Veil, andScrim, whose background and opacity are the veil’s fill. State:LoadingOverlayState::Loading.PageLoader::new(title)stands in the place of a whole page, a window or a pane while it starts: a ring of 28 over the title and, with.description(&str), a line that says what is being done, in the middle of the room it is given. It is as large as that room (it fills its width, and its height where what holds it has one) and keeps 24 from its sides; a title or a description longer than the room wraps, centred. It paints no surface: it stands on the page’s, and the board’s box of 280 by 180 is the page it is drawn on..spinner(Spinner)gives a spinner of the app’s in place of the ring, as it is given. To what reads the tree it is onestatus, called by its title and described by its description; the spinner in it is no status of its own. Parts:PageLoaderPart::Root,Spinner(laid over the spinner’sIndicator: the ring’s side),Text,Title(14, medium,Foreground),Description(13,MutedForeground, 4 under the title); the ring is 14 over the text. State:PageLoaderState::Description. A renderer hasview.root(),view.spinner()andview.text().- A renderer that draws another spinner starts from
view.indicator()andview.label();view.name()is what it is called.
Skeleton
Section titled “Skeleton”A placeholder in the shape of what is loading.
use lurq::{components::{Column, Row}, ui::{Skeleton, SkeletonAnimation}};
Skeleton::line();Skeleton::circle(40.0);Skeleton::block(200.0, 112.0);Skeleton::paragraph(4).animation(SkeletonAnimation::Shimmer);
// A row of a list, in one status for tooling.Skeleton::status( "Loading people", Row::new() .spacing(12.0) .child(Skeleton::circle(40.0)) .child(Column::new().flex(1.0).spacing(8.0).child(Skeleton::line()).child(Skeleton::line().width(140.0))),);| Builder | |
|---|---|
Skeleton::line() | A line of text: as wide as the room it has, 12 high |
Skeleton::circle(size) | A face, an icon: round, size across |
Skeleton::block(width, height) | An image, a chart, a card. Length::Fill is all the room it has |
Skeleton::paragraph(lines) | Lines 10 apart; the one before the last a little shorter, the last shorter still |
width(length), height(length) | The app’s size over the shape’s. For a paragraph, the width of all of it and the height of each line |
min_width, max_width, min_height, max_height, radius(..) | The rest of what an app lays on a bone: its least and most sizes and its corners, over the shape’s. For a paragraph, the widths are of all of it, the heights and the radius of each line |
flex(factor), flex_shrink(factor) | Its share of the room left in its row or column, and how much of its size it gives up where there is too little, as an element’s. lurq has no margins: a gap or a padding around it says where it stands |
animation(SkeletonAnimation) | Pulse (the default), Shimmer or None |
motion(SkeletonMotion) | How it pulses or shimmers, in place of the theme’s (theme.set_skeleton_motion(..)): SkeletonMotion::SMOOTH (the default), or SkeletonMotion::stepped(per_second), with .period(duration) and .dim_to(opacity) |
Skeleton::status(label, content) | A status called label around a group of skeletons |
state(name, on), style(part, ..), rules(&recipe), id, key | As a button has them |
- A skeleton is nothing to tooling that reads the tree: nothing of it is described, so it is left out as any box with no text, id or handler is. What is loading is said once, by
Skeleton::statusaround a group of them. - A skeleton pulses with
ui::SKELETON_PULSE, from whole to half and back inSKELETON_PULSE_PERIOD; one that shimmers has a sheen as wide as itself cross it inSKELETON_SHIMMER_PERIOD, from wholly before its start to wholly past its end, whatever its width: in a row three times the skeleton’s width centred on it, the room before the sheen grows from nothing to two thirds of the row (ui::SKELETON_SHIMMER, a width in percent). Both play on the animation clock, so every skeleton on screen pulses as one, and the sheen crosses all of them at once. Where motion is reduced a skeleton stands still, whatever its motion. - A
SkeletonMotionsays how they move: smoothly, or in steps (SkeletonMotion::stepped(20)), each pose held until the next and no frame asked for between, so that a window with skeletons shown draws 20 frames a second and none more, all of them changing at the same moment; how long a pulse, or a crossing of the sheen, takes (.period(..),SKELETON_PULSE_PERIODunless told); and how far a pulse dims at its middle (.dim_to(0.55), an opacity in hundredths between 0 and 1, 0.5 unless told;dimmed()reads it), which a sheen does not. Skeletons that dim alike pulse in one phase; each depth has keyframes of its own in every window,SKELETON_PULSEthe one of half. A theme gives the motion of every skeleton not told its own:app.theme().set_skeleton_motion(SkeletonMotion::stepped(20).period(Duration::from_millis(1600))). - Parts:
SkeletonPart::Root(the box of a shape, or the column of a paragraph’s lines),Bone(a shape),Sheen(the fill of its middle; it is as wide as the bone). A theme’s renderer is givenSkeletonViewwith itsmotion, and builds the root withview.root(), which carries the id, the key and the app’sflex. The shapes are the variants ofSkeletonShape:Line,Circle,Block,Paragraph. - In the design every shape is in
Muted; a line is 12 high andradius-sm, a circleradius-full, a block 200 by 112 andradius-lg; a paragraph’s lines are 10 apart, its last two 92 and 60 hundredths of its width. The sheen runs from the shape’s fill toSecondaryHoverand back. - The board’s media row and card are built from these and are no components of their own: the gallery’s Skeleton page has both, with their code.
Progress
Section titled “Progress”How far a piece of work is: a file uploading, items being copied. A bar along a rail, the thin bar across the top of a window, or a ring with the value in its middle.
use lurq::ui::{Progress, ProgressSize, ProgressVariant, RingProgress};
// A fraction of one.Progress::new(0.62).label("Uploading theme.json").show_value(true).size(ProgressSize::Md);
// 42 of 128 items, said as the app says it.Progress::new(42).max(128).show_value(true).value_text(|done| format!("{done} of 128"));
// Work whose end is not known.Progress::indeterminate().label("Connecting");
// The thin bar across the top of a page, first in the page's column.Progress::new(loaded.get()).top_bar(true);
// The same value around a circle, with it in the middle.RingProgress::new(0.7).variant(ProgressVariant::Success);| Builder | |
|---|---|
Progress::new(value) | How far the work is: a fraction of one, or of the range min and max say. A value outside the range fills nothing or all of the rail; its text says what it is |
Progress::indeterminate() | Work whose end is not known: a segment crosses the rail again and again |
value(n), min(m), max(m) | How far the work is, and its range: none of it done (0 when not given) and the whole of it (1 when not given), as a meter says them. A range of nothing or less: nothing is done |
variant(ProgressVariant) | The color of what is filled: Neutral (primary), Info, Success, Warning, Destructive, the tones’ order and names as every component’s |
size(ProgressSize) | The rail’s height: Sm 4, Md 6, Lg 8 (the default). A ring of 40, 56 or 72 |
label(&str) | What the work is, over the start of the rail, and what the progress is called |
label_hidden(bool) | The label is what the progress is called, and is not drawn |
show_value(bool) | The value over the end of the rail, as a percentage or as value_text writes it. Off unless told, as the design’s bar draws none; none while it is not known. A ring shows it unless told not to, as the design’s ring does |
value_text(Fn(f64) -> String) | Writes the value as the app does, given the value as it is: “42 of 128”. Not given, its share of the range as a percentage |
description(&str) | The line under the rail: what is left, “2 minutes left”. It describes the progress to tooling |
top_bar(bool) | The thin bar across the top of a window or a surface: 3 high, no rail, as wide as what holds it |
width(impl Into<Length>) | How wide the progress is: 240 when not given |
state(name, on), style(part, ..), rules(&recipe), id, key | As a button has them. id is the id of the root |
- A label longer than the rail is cut with an ellipsis on one line, before the value, which is never cut.
- A progress is read, not operated: it takes no focus and no press. What is filled is a share of the rail, and moves to a new value over the theme’s slow duration; while motion is reduced it is there at once.
- Work that is not known runs a segment of 90 of 240 across the rail, growing out of its start and leaving at its end, once in
ui::PROGRESS_PERIOD(1.6 s), in phase with every other such bar. While motion is reduced the segment stands still 70 of 240 from the start of the rail, where no value would be, as the board draws it. - Parts:
ProgressPart::Root(the header over the rail),Header(the label and the value),Label,Value,Track(the rail),Fill(what is filled; the moving segment),Description(12 inMutedForeground, under the rail, as a meter’s). States:ProgressState::Indeterminate,TopBar. - In the design the rail is 240 by 8, round, in
Secondary, filled inPrimary, orSuccess,Warning,Destructive. Under a label and in a dialog it is 6, in a row of a list 4. The label is 8 over the rail in the label’s type (13, medium) andForeground; the value is at the end in the mono type of 11,MutedForeground. The top bar is 3 high with no rail, its fill square where it starts and round 2 where it ends. - A ring (
RingProgress) is 72 across, the ring a tenth of that wide, inSecondary, with what is done over it in the variant’s color from the top and clockwise, and the value in the middle in the label’s type of 13 at a weight of 600 (12 and 11 in the rings of 56 and 40). Nothing is painted in its middle, so it sits on any surface. It takesvalue,min,max,variant,size,label(its name to tooling: the board draws no text beside it),show_value,value_text,state,style,rules,idandkey. It always knows the value: what does not is a spinner’s. - The ring is two round boxes one over the other: the track, whose inside border is the ring, and the fill, whose inside border, as wide and in the arc’s color, is one dash as long as the arc with a gap of the rest of the circle. A border’s dashes start at the top of a circle and run clockwise, and their period is fitted to the outline, so a dash and a gap that make the circle are one dash of it. The arc moves round to a new value, and fades in from nothing, over the theme’s slow duration (
Transition::border_dash(),border_color()); while motion is reduced it is there at once. Parts:RingProgressPart::Root,Track(its border is the ring: its width and the color of what is not done),Fill(its border’s color is the arc’s),Middle(holds the value, paints nothing),Value. - To what reads the tree (
lurq_snapshotof the MCP server) a progress and a ring are aprogressbarcalled by their label and described by the description, witha11y_valuenow,a11y_valuemin,a11y_valuemaxanda11y_valuetext(the value as it is written), the numbers written as a meter’s are; one that does not know how far the work is has no value. - A renderer that draws another progress has
view.fraction(),view.value(),view.max(),view.value_text(),view.root()(the root with its name to tooling),view.header()andview.track()(the rail with what is filled, or with the moving segment).view.min()andview.description()(the line under the rail) are there too. A share of something that is not work under way is a meter’s. A ring’s renderer hasview.fraction(),view.value_text(),view.side(),view.thickness(),view.root(),view.track(),view.arc()(the fill with its dash) andview.middle(). A value as half a ring is a gauge’s.
How much of a known range a value takes, in segments, and whether that is good: the space a disk has used, a battery’s charge, the seats of a plan. Where a progress bar says how far a task has come, a meter says where a value stands.
use lurq::ui::{Meter, MeterVariant};
// The board's: good under 64, a warning to 96, bad past it.Meter::new(96) .max(128) .low(64) .high(96) .label("Disk space") .value_text(|used| format!("{used} of 128 GB")) .description("Running low. Free up space soon.");
// A battery: the higher the better.Meter::new(18).low(20).high(80).optimum(100).label("Battery");
// One tone, no parts.Meter::new(12).max(20).segments(20).variant(MeterVariant::Info).label("Seats used");| Builder | |
|---|---|
Meter::new(value), value(..) | The value, impl Into<f64> |
min(..), max(..) | The range, 0 to 100 unless given, as a progress bar and a slider say it |
low(..), high(..) | Where the low part of the range ends and the high part starts: each filled segment is in the tone of its part |
optimum(..) | The best value, min unless given: the part it is in is good (Success), the part next to it a warning (Warning), the far one bad (Destructive), as a web page’s meter judges them |
variant(impl Into<Name>) | A MeterVariant (Neutral, Info, Success, Warning, Destructive), or a variant a theme adds: the tone of every filled segment of a meter with no low and no high |
segments(usize) | How many segments the range is cut into, the board’s 16 unless given |
label(&str) | What it measures, over the segments: its name to tooling |
description(&str) | The line under the segments: what the value means. In the tone of the value where that is a warning or bad |
value_text(Fn(f64) -> String) | Writes the value as the app does. Not given, “96 of 128” |
state(name, on), style(part, ..), rules(&recipe), id, key | As a button has them |
- The value fills the segments it reaches, to the nearest: 96 of 128 fills 12 of 16. A value under
minfills none and one overmaxfills them all; its text says what it is. - A segment’s tone is that of the part of the range its middle is in, so the board’s 64 to 96 are the four warning segments 9 to 12.
- To what reads the tree it is a
metercalled by its label and described by its description, witha11y_valuenow,a11y_valuemin,a11y_valuemaxanda11y_valuetext. - Parts:
MeterPart::Root,Header,Label,Value,Segments,Segment,Description. States:MeterState::Filled(of a segment). The variant a segment is resolved with is the tone of its part of the range; the root’s is the tone of the value. - In the design the meter is 260 on the board and as wide as what holds it here, its header, its segments and its description 8 apart. The label is 13 at 500 in
Foreground, the value the mono type at 11 inMutedForegroundat the end of its row. The 16 segments are 8 high, 2 apart, with a radius of 2: a filled one in the tone of its part, an empty one inSecondary. The description is 12, inWarningorDestructivewhere the value is, and inMutedForegroundwhere it is good. - A theme’s renderer is given
MeterView:view.segments(each aMeterSegmentwith its tone and whether it is filled, andsegment.render()), the value, its range, its tone and its text,view.header(),view.segments(),view.description()andview.root(content).
A value of a known range as the share of a half ring, its reading in it: the load of a processor, the speed of a link, the heat of a card. Its ring is drawn on the canvas, behind the canvas feature.
use lurq::ui::Gauge;
Gauge::new(70).label("CPU");
// A temperature: bad past 85, its reading as the app writes it.Gauge::new(86).min(20).max(100).low(60).high(85).label("GPU").value_text(|degrees| format!("{degrees}°"));| Builder | |
|---|---|
Gauge::new(value), value(..) | The value, impl Into<f64> |
min(..), max(..) | The range, from the ring’s start to its end: 0 to 100 unless given, as a meter says it |
low(..), high(..), optimum(..) | The parts of the range, as a meter’s: the value’s share is in the tone of its part |
color(impl Into<BackgroundColor>) | The color of the value’s share of a gauge with no parts, a role of the palette or a color: Chart1 unless given |
label(&str) | What it measures, under the ring between its bounds: its name to tooling |
value_text(Fn(f64) -> String) | Writes the reading. Not given, the value’s share of the range in percent, “70%“ |
bound_text(Fn(f64) -> String) | Writes the bounds under the ring. Not given, as they are: “0”, “100” |
state(name, on), style(part, ..), rules(&recipe), id, key | As a button has them |
- The half ring runs from the least value at its start, the left, to the greatest at its end, and the value takes its share from the start. A value outside the range takes none or all of it; its reading says what it is.
- The ring is painted with
Canvas::paint, sharp at every scale; its reading, its label and its bounds are text, laid over it and under it. Its canvas holds avalueitem where the value’s share ends, with the reading as its text. - To what reads the tree it is a
metercalled by its label, witha11y_valuenow,a11y_valuemin,a11y_valuemaxand its reading asa11y_valuetext. - Parts:
GaugePart::Root,Arc(the canvas: its width and height),TrackandValue(drawn in their part’s background, the track as thick as its part’s width),Reading,Range,Label,Bound. The variant it is resolved with is the tone of the value where it has parts. - In the design the gauge is 140 wide, a half ring 140 across and 72 high whose inner edge is 0.78 of its outer, so 15.4 thick: the track in
Secondary, the value’s share inChart1, both with square ends. The reading is 20 at 600 inForegroundin the ring, its foot 10 over the ring’s. Under the ring, 4 from it, the bounds at the ends, the mono type at 11 inMutedForeground, and the label between them, 12 at 500 inForeground. - A theme’s renderer is given
GaugeView: its value, range, share and reading, the bounds’ texts, its label,view.arc(),view.range(),view.root(content)andview.render().
Password Input
Section titled “Password Input”An input whose text is masked, with an eye at its end that shows it and hides it again, and under it, where the app says so, a meter of how strong the password is.
use lurq::ui::{PasswordInput, PasswordStrength};
// password: Signal<String>, shown: Signal<bool>PasswordInput::new(password.clone()) .placeholder("Password") .bind_reveal(shown.clone());
// A password being chosen, judged by the app as it is typed.PasswordInput::new(chosen.clone()) .new_password(true) .bind_reveal(shown.clone()) .strength(judge(&chosen.get()));| Builder | |
|---|---|
PasswordInput::new(value) | A password input bound to a Signal<String>: what is typed is set on it |
reveal(bool), on_reveal(Fn(bool)) | Whether the password is shown as it is; called on a press of the eye with whether it is to be shown |
bind_reveal(Signal<bool>) | Shown while the signal is true, which the eye turns |
reveal_button(bool) | The eye at the end of the box: there unless the app says not |
show_label(&str), hide_label(&str) | What the eye is called to tooling, in place of “Show password” and “Hide password” |
mount(ctx) | The input mounted where it is declared: with no bind_reveal and no on_reveal, it keeps whether the password is shown, and the eye turns it |
strength(Option<PasswordStrength>) | The meter under the input: Weak, Fair, Good, Strong fill 1 to 4 of its bars |
strength_text(&str) | What the meter says, in place of “Weak password” to “Strong password” (PasswordStrength::text) |
new_password(bool) | The password is being chosen, not entered: the platform may offer a strong one |
input_rules(&recipe) | Rules over the theme’s recipe for the input it is made of |
placeholder, icon, size, invalid, warning, valid, read_only, disabled, label, full_width, on_input, name | As an input has them |
state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. id is the id of the control |
- While the password is masked the dots are 1 apart; the placeholder is set as any placeholder, with no spacing of its own.
- It is an input in every other way: its box, its sizes, its judgments, a field’s label. Whether the password is shown is kept by a
Signal<bool>bound withbind_reveal, by the app withrevealandon_reveal, or, with neither, by the input mounted withmount(ctx). The eye is drawn unlessreveal_button(false); converted into an element with neither a signal nor a handler, the input is its still form, and the eye turns nothing. - Tab reaches the input and then the eye, which Space and Enter press. To tooling the eye is a
buttoncalled “Show password” or “Hide password”, witha11y_pressed. - Masked, the password is not copied or cut, the platform’s keyboard keeps it out of its suggestions, and tooling (
lurq_snapshot,lurq_set_valueof the MCP server) reads only its dots andmasked=true. Shown, it is what the screen shows, to tooling too. Shown or not it holds a password to the platform (ContentKind::Password, orNewPassword), which may offer to fill it in. - Parts:
PasswordInputPart::Root(the input, the meter and its message, one under another),Mask(the room between the dots),Toggle(the eye),Strength(the meter),Bar(a bar the strength does not reach),Fill(one it does),Description(what the meter says). States:PasswordInputState::Revealed,Disabled,FullWidth, and the strength by its name (weak,fair,good,strong). The box, its text and its placeholder are the input’s parts, styled by the theme’s recipe for an input orinput_rules. - In the design the dots are 1 apart; the eye is 16 in
MutedForeground, 12 from the end of the box and 8 after the text, inForegroundunder the pointer; while the password is shown it is an eye with a line through it (icons::EYE_OFF), inForeground. The meter is 8 under the box: four bars 4 high and 4 apart, round, inInputwhere the strength does not reach and in its color where it does,Destructivefor weak,Warningfor fair,Successfor good and strong; the message is 8 under it in a caption’s type in the same color. - A renderer that draws another password input has
view.input(the input’s view:render_with_endis crate-private, so it lays the eye overview.control()itself),view.control()(the masked text input with room at its end),view.toggle(),view.strength_meter()andview.description().
Search Field
Section titled “Search Field”An input for a query: the search icon before the text, a button that empties it, and the hint of the key that reaches it.
use lurq::ui::SearchField;
// query: Signal<String>SearchField::new(query.clone()) .placeholder("Search components") .shortcut("/") .on_submit(|query| search(query));| Builder | |
|---|---|
SearchField::new(value) | A search field bound to a Signal<String>, which the app filters by as it changes |
shortcut(&str) | The key that reaches the field, at its end while it is empty: /, Ctrl K. The app binds the key |
on_submit(Fn(&str)) | Called on Enter with what the field holds. The focus stays in the field |
ref_element(ElementRef) | The ref of the field’s text input: what the app focuses on the key the hint shows (ctx.focus(&field)) |
clear_label(&str) | What the clear button is called to tooling, in place of “Clear search” |
clearable(bool) | The clear button while it holds something, and Escape that empties it: on unless the app says not |
icon(impl Into<IconChoice>) | The icon before the text in place of the search icon, or None for none |
input_rules(&recipe) | Rules over the theme’s recipe for the input it is made of |
placeholder, size, invalid, warning, valid, read_only, disabled, label, full_width, on_input, name | As an input has them |
state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. id is the id of the control |
- The hint of a key is never wider than 112: a longer one is cut with an ellipsis, and the icon and the text keep their room.
- While it holds something a clear button is at its end, which empties it and takes no focus, so the caret stays in it; Escape does the same while the focus is in it, and keeps the focus there. Escape in an empty field does what it does in any input. A read-only or disabled field has no clear button, and Escape does not empty it.
- The clear button is no stop of Tab: from the keyboard Escape does what it does. The hint shows while the field is empty; the field does not bind the key, which the app does and focuses the field on (
ctx.focus). - To tooling the field is a
searchboxand its button abuttoncalled “Clear search”. - Parts:
SearchFieldPart::RootandControl(what the field says of the input’s root and box: its width, its padding),Trailing(what is at the end of the box),Clear,Shortcut(the hint). States:SearchFieldState::Filled,FullWidth. The box, its text, its placeholder and its icon are the input’s parts. - In the design the field is 280 by 36, padded 10 at its start and 8 at its end; the search icon is 16 in
MutedForeground, 8 before the text. The clear button is a circled cross of 16 inMutedForeground,Foregroundunder the pointer. The hint is 20 high, padded 6, 4 round onMutedin an edge of 1 inBorder, in the mono type of 11 inMutedForeground. - The field renders again as it fills and empties, to show the clear button or the hint: it reads its signal as it is built.
- A renderer that draws another search field has
view.input,view.control()(the text input with its keys and room at its end),view.clear()andview.shortcut().
Input Group
Section titled “Input Group”An input joined with what stands before and after it into one box: a scheme, a domain, a unit, an icon, the button that sends it.
use lurq::ui::{Button, ButtonVariant, Input, InputAddon, InputGroup, Select, icons};
InputGroup::new(Input::new(site.clone())).leading("https://").trailing(".com");
InputGroup::new(Input::new(email.clone()).placeholder("Email")) .leading(InputAddon::icon(icons::MAIL)) .trailing(Button::new("Invite").variant(ButtonVariant::Ghost).on_click(invite));
InputGroup::new(Input::new(site.clone())).leading(Select::new(scheme.clone(), [("https", "https://"), ("http", "http://")]));| Builder | |
|---|---|
InputGroup::new(input) | A group around an input, which keeps its own value, handlers and id |
leading(addon), trailing(addon) | What stands before and after the input, in order: a text (&str), InputAddon::icon(name), a Button, a Select |
label(&str), read_only(bool), name(..), on_submit(..), force(..) | Said of the input in the group, as an input has them |
size(InputSize) | The input’s, and each button’s and select’s in the group |
invalid, warning, valid, disabled, full_width, on_input | The input’s judgment and the box’s edge; nothing in a disabled group takes input; 280 wide or as wide as what holds it |
state(name, on), style(part, ..), rules(&recipe), id, key | As a button has them. id is the id of the box |
- The corners of the box are the group’s: what is at its ends is round where the box is, every other corner is square. A line is between two neighbours. The input has no edge or fill of its own: the box’s edge says what it holds, and turns the ring’s color under the pointer. The ring of the focus is the focused part’s own, drawn over its neighbours and the box’s edge.
- An icon beside the input is in its box: before it, the input’s own icon; after it, over the end of the input. An icon away from the input stands on the muted fill as a text does.
- A button and a select keep what they do and their variant; the group gives them its size and its corners, and a select no edge or fill of its own. Each is its own stop of Tab.
- In a field the input is called by the field’s label and judged as the field is, and the group is disabled where the field is.
- Parts:
InputGroupPart::Root(the box),Field(what the group says of the input’s root),Control(of the input’s box),Addon(a text or an icon on the muted fill),AddonIcon,Separator(the line),Button(of a button’s root),Select(of a select’s trigger). States:InputGroupState::Disabled,FullWidth, and the input’s size and judgment by their names. - In the design the box is 280 by 36,
Backgroundin an edge of 1 inInput, 6 round. A text addon is onMuted, padded 10, in 13 andMutedForeground(12 small, 14 large); the line between two parts is 1 inInput; the input is padded 10. A disabled group is half opaque onMuted. - A renderer that draws another group has
view.input,view.before,view.after,view.addon(addon, index),view.field()andview.separator().
Number Input
Section titled “Number Input”A number a person types or steps: a quantity, a price, a size in pixels.
use lurq::ui::{NumberFormat, NumberInput, NumberInputLayout};
// A number there always is, between 1 and 99.NumberInput::new(quantity.clone()).min(1).max(99).label("Quantity");
// A price with two decimals, its thousands set apart, the buttons stacked at the end.NumberInput::new(price.clone()) .min(0.0) .step(0.5) .precision(2) .format(NumberFormat::new().prefix("$").grouping(true)) .layout(NumberInputLayout::Stacked);
// A number that may be left out: an emptied field is None, not 0.NumberInput::optional(limit.clone()).placeholder("No limit");
// The app's own value, told back; and saved when Enter, the focus leaving or a step ends a change.NumberInput::controlled(seats.get(), move |value| seats.set(value)).on_change_end(move |value| save(value));| Builder | |
|---|---|
NumberInput::new(Signal<f64>) | Bound to a number there always is: an emptied field takes back the number it had when it is left |
NumberInput::optional(Signal<Option<f64>>) | Bound to a number that may be none: an emptied field sets None |
NumberInput::controlled(Option<f64>, on_change) | The app holds the value: it shows it, tells on_change each change a person makes, and shows what the app answers with |
min(v), max(v) | The ends of the range, where it has them, any number (impl Into<f64>). With no least value a minus can be typed and Home moves the caret; with no greatest End does |
step(v) | How far apart the values a step takes it to are, from the least (from 0 with none): 1 when not given |
precision(usize) | How many decimals the value keeps and shows: as many as the step has when not given. With none no decimal separator is taken |
format(NumberFormat) | How the number is written out of the focus: prefix, suffix, grouping, separators(decimal, group), or NumberFormat::custom(format, parse), the app’s own |
layout(NumberInputLayout) | Split (the board’s: a minus at the start, a plus at the end, the number in the middle), Stacked (a chevron up over one down at the end, the number at the start), Bare (no buttons) |
size(NumberInputSize) | Sm 32, Md 36, Lg 40 high, the type 13, 14, 15 |
placeholder(&str) | What an empty input says |
invalid, warning, valid, read_only | As an input has them. A read-only one is focused and selected, and its keys and buttons change nothing |
on_change(Fn(Option<f64>)) | Called with the value each time a person changes it: as it is typed, stepped, put right or emptied. Each call adds |
on_change_end(Fn(Option<f64>)) | Called with the value when a change is over, where it is another than before: Enter or the focus leaving after typing, each step of a key, Home and End, and the release of a button held down, however many steps it took. Each call adds |
increase_label(&str), decrease_label(&str) | What the buttons are called to what reads the tree: “Increase” and “Decrease” when not given |
name(..) | The name of its text in a form’s data. A form’s number is bound with NumberInput::new(form.number("seats")) |
label, full_width, disabled, state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As an input has them. id is the id of the box that is typed in |
- What is typed is kept as text while it is typed, and is the value as soon as it is a number. A minus (first, where the range has room below 0), digits and one decimal separator (where the precision keeps decimals) are taken; anything else is not. A number pasted as it is written (
$2,000) is read and typed as the number. On Enter and when the focus leaves, the text is put right: the number rounded to the precision, kept in the range and written in the format; what is not a number goes back to the value. When the range changes under the value (amaxset lower than it), the value is taken into the range at once, as a slider’s is, in both forms: an input bound to a signal shows it, writes it and tellson_change; a controlled one, whose value the app holds, shows the clamped value, tellson_changeonce, as a press of a stepper would, and shows what the app answers with. - In the focus the number is typed plain, with the decimal separator and nothing around it; out of it, it is written in the format. A locale’s decimal separator is the format’s:
NumberFormat::new().separators(',', '.'). - Up and Down take a step, Page Up and Page Down ten, Home and End go to the least and the greatest value where the range has them. A step from a value between two steps goes to the next one; from an empty field it goes to 0, or to the end of the range nearer to it. A wheel over the input scrolls what it is in and leaves the number as it is.
- The buttons take a step when pressed, and while held another after 400 ms and then every 50 ms. They are not stops of Tab and take no focus: a press leaves the focus on the number being typed. The one toward an end of the range the value is at is disabled and dimmed (states
AtMin,AtMax). - Parts:
NumberInputPart::Root(its width),Control(the box that is typed in, which holds the ring of the focus),Placeholder,Buttons(what holds the buttons over the box: its inset and corners),Decrease,Increase,Separator(the line between a button and the number),Icon. Variants:NumberInputLayout. States:NumberInputState::Invalid,Warning,Valid,ReadOnly,Disabled,FullWidth,AtMin,AtMax. - In the design the box is 132 by 36, an input’s box (the
Backgroundfill in an edge of 1 inInput, 6 round), its number in the middle in the mono type at 14 inForeground. The minus and the plus are 36 wide at the ends, each with a line of 1 inInputbetween it and the number, their glyphs 16; under the pointer a button is inHighlight. The ring’s color under the pointer, a line of 2 inside the box in the focus, and the judgments’ colors are the input’s. - The board’s mobile quantity stepper is the number input restyled: rules make the
Control44 high, round, inSecondarywith no edge, the number in the sans type at 16, semibold; theButtonswith no inset and round;DecreaseandIncrease44 wide; theSeparator0 wide; theIcon20. The gallery’s page has them. - To what reads the tree (
lurq_snapshotof the MCP server) the box is aspinbuttoncalled by its label, witha11y_valuenow,a11y_valuetext(as it is written),a11y_valueminanda11y_valuemax; the buttons arebuttons called “Increase” and “Decrease” (or their labels), witha11y_disabledat an end of the range, their ids the input’s with-increaseand-decreaseafter it. - A renderer that draws another number input has
view.control()(the box with all of its typing, keys and putting right),view.button(part, icon, steps),view.separator(),view.buttons()(laid over the box as the layout has them) andview.buttons_reach()(how far they reach in from each end).
Input OTP
Section titled “Input OTP”A one-time code: a few characters typed one to a cell, the code a message or an authenticator app gives to prove who a person is.
use lurq::ui::{Field, InputOtp, InputOtpKind};
Field::new( "Verification code", InputOtp::new(code.clone()) .groups([3, 3]) .on_complete(move |code| verify(code)),).description("We sent a code to ivan@lurq.dev.");
// A recovery code of letters and digits, taken as capitals however it is typed.InputOtp::new(recovery.clone()) .length(8) .groups([4, 4]) .kind(InputOtpKind::Alphanumeric) .uppercase(true);| Builder | |
|---|---|
InputOtp::new(Signal<String>) | The code. The cells show what the signal holds, and what is typed is set on it |
length(usize) | How many cells it has: 6 unless it says |
groups(sizes) | The sizes of the groups of cells, from the first: [3, 3] puts a dash after the third cell. Cells past the groups are a group of their own |
kind(InputOtpKind) | Digits (the default) or Alphanumeric. Anything else typed or pasted is not taken |
uppercase(bool) | A letter is taken as a capital |
mask(bool) | A dot for each character in place of it, as a PIN is shown |
on_change(impl Fn(&str)) | Called with the code when a person changes it: a character typed, pasted or deleted. Not when the app sets the signal |
on_complete(handler) | Called with the code when an edit fills its last cell. A second handler is called after the first, as every on_* is |
size(InputOtpSize) | Sm, Md, Lg: cells of 32 by 36, 36 by 40, 40 by 44, with type of 14, 16, 18 |
invalid, warning, valid, read_only, disabled, label, name | As an input has them; name is the whole code’s in its form |
state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. id is the id of the input under the cells |
- To a person it is one field. Tab puts the focus on the first empty cell. Typing fills the cell that has the focus and goes on to the next; typing on a filled cell replaces its character. Past the end of a full code what is typed goes nowhere, until a key or a click puts the focus back on a cell: the last cell is not typed over, and
on_completeis called once as the code fills. Ctrl+A (Cmd+A) selects the whole code: Backspace or Delete then clears it, and a character typed starts it again. Backspace empties the cell that has the focus, or, on an empty one, goes back and empties the one before; Delete empties it and stays. Left and Right move, no further than the first empty cell; Home and End go to the first cell and to the first empty one. A click puts the focus on the cell clicked, or on the first empty one where that is before it. - A code has no gaps: emptying a cell before the last filled one moves the cells after it up.
- It is a text input, which is always bound to a signal: it has no
controlledform.kindsays what the code is made of, not a tone: it is not avariant. - A value the app sets is taken as typing takes it: what is not of the code’s kind is dropped, letters are made capitals where it says, and no more than its cells are kept, and the signal is set to what is left.
- A paste of a whole code, or more, fills every cell from the first; a shorter one fills the cells from the one that has the focus. What the code does not take of it (spaces, dashes) is dropped, so
123-456is123456. - To a form, to tooling and to the platform it is one text input: under the cells is the engine’s
TextInput, bound to the code, which draws nothing of its own. It is the one stop of Tab, the onetextboxto what reads the tree (lurq_snapshotof the MCP server), called by its label, with the code as its value, and the one value of its form under itsname. It says it holds aContentKind::OneTimeCode, so a phone offers the code from a message that just came, and asks for the digits keyboard where the code is of digits. A masked code is a masked input. - The cell the focus is on, and whether the input has the focus, are kept by the code’s signal for as long as its input is in the tree, since a builder keeps nothing between renders: two codes bound to one signal share them.
- Parts:
InputOtpPart::Root(the row of cells and separators, and the room between them),Cell,Value(the character, or its dot),Caret(in the empty cell that has the focus),Separator(the dash between groups). States:InputOtpState::Invalid,Warning,Valid,ReadOnly,Disabled,Masked, and on a cell of its ownActive(the focus is on it) andFilled. - In the design a cell is 36 wide and 40 high, 6 from the next, in the background’s fill with an edge of 1 in the
Inputcolor,radius-mdround, its character in the mono type at 16 inForeground. The cell the focus is on has a line of 2 inside it in theRingcolor, and while it is empty a caret 1.5 wide and 18 high inForeground, which blinks unless the theme reduces motion. The dash between groups is theminusglyph at 16 inMutedForeground, 6 from the cells on either side. A judgment colors every edge and the ring; a disabled code is half opaque on the muted fill, a read-only one on the muted fill in theBordercolor. - The mobile skin of the board (Mobile/OTP Field) is a rule of the theme:
Root8 apart,Cell46 by 56 andradius-lg,Valuein the sans type at 22 and semibold,Caret2 by 24. - A renderer that draws other cells starts from
view.input(), the behavior, and lays its own cells over it:view.characters,view.shown(index)(what a cell shows, its dot where masked),view.active(the cell the focus is on, while the code has it),view.separators, andview.cell_part(index, part)for the style of a part of one cell.view.cell(index),view.separator()andview.cells()are the default ones. A cell built byview.cell(index)is one a click is known to be on.
Swatch Picker
Section titled “Swatch Picker”One color chosen among swatches in a grid: the color of a label, of a highlight, of an event in a calendar.
use lurq::{node::color::Color, ui::{Swatch, SwatchPicker}};
// Bound to the app's signal, which a choice sets.SwatchPicker::new(color.clone(), ["#EF4444", "#F97316", "#F59E0B", "#22C55E", "#3B82F6", "#A855F7"]) .columns(3) .label("Label color");
// The app's own values, each with its color: none chosen until a person chooses.SwatchPicker::optional(label.clone(), [ Swatch::of(Label::Bug, Color::from_hex("#EF4444")).label("Bug"), Swatch::of(Label::Docs, Color::from_hex("#3B82F6")).label("Docs"),]);
// Held by the app, which is told what is chosen and shows what it answers with.SwatchPicker::controlled(app.color(), swatches, |color: &Color| app.set_color(*color));| Builder | |
|---|---|
SwatchPicker::new(value, swatches) | Bound to a Signal<T>: the swatch of its value is the chosen one, and choosing another sets it. T is Color, or the app’s value the swatches carry |
optional(Signal<Option<T>>, swatches) | The same, holding none until a person chooses: Tab then enters at the first swatch |
controlled(value, swatches, on_change) | The app holds the value: a choice is told to on_change, and the picker shows what the app answers with. It keeps nothing between renders |
on_change(handler) | Told the value a person chooses (|color: &Color|, &T the compiler checks); not for the swatch chosen already, nor when the app sets the signal. A second handler is called after the first |
swatch(swatch), swatches(swatches) | More swatches after those given: a Color, a hex ("#EF4444", which panics where it is no color), or a Swatch |
Swatch::new(color), Swatch::of(value, color) | A swatch whose value is its color, or the app’s value; with label(&str) (its hex where it has none), disabled(bool), id, key |
columns(usize) | How many swatches a row holds: 6, the board’s. Up and Down move the focus by as many |
size(ColorSwatchSize) | The swatches: Sm 20, Md 24 (the board’s), Lg 32 |
framed(bool) | A panel of its own (the default), or the grid alone, for a popover or a picker that frames it |
label(&str), invalid(bool), disabled(bool) | What it is called to what reads the tree; the panel’s edge in Destructive; no swatch taking input, each dimmed |
state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. force draws the swatch Tab stops on |
- Exactly one swatch is chosen, ringed in
Foreground. The grid is one stop of Tab, at the chosen swatch or the first that is not disabled; Left and Right move along a row and on to the next (a focus group, without going round), Up and Down a row in the same column, Home and End to the first and the last swatch, and a disabled swatch is passed by. A click, Enter or Space chooses; the arrows only move the focus. - It is a control a field holds: the field names it, judges it invalid and disables it.
- Each swatch is a color swatch’s anatomy: its parts and states (
ColorSwatchPart,ColorSwatchState::Selected,Disabled) are resolved for each, under the picker’s rules forSwatchPickerPart::Swatch. A color that is not opaque stands over the swatch’s checkerboard. - Parts:
SwatchPickerPart::Root(the panel, or the bare grid),Row(the room between swatches),Swatch(laid over each swatch’s root). States:SwatchPickerState::Framed,Invalid,Disabled. - In the design the panel is in
Popoverwith an edge of 1 inBorder, the large radius and the medium shadow, padded 10, its rows 6 apart; the swatches are 24, the small radius, 6 apart, each with an edge of 1 inStatePressed(the board’s black at 8%), the chosen one ringed with 2 inForegroundoutside it. The board’s panel is 196 wide, 2 more than its six swatches and its padding take: the picker is as wide as its rows, 194. The board draws no focus, no disabled swatch and no invalid picker: the focus is the theme’s ring on the swatch, a disabled swatch is dimmed, and an invalid picker’s edge is inDestructive. - To what reads the tree it is a
listboxcalled by its label, ofoptions called by their labels (or their colors’ hex), witha11y_selected, anda11y_disabledon one that cannot be chosen. - A renderer that draws another picker has
view.swatches(each aSwatchItemwith its color, label, whether it is chosen or disabled, and its recipe),view.entry(),view.root()(the grid’s focus group with its role) andview.swatch(index)(a swatch with its keys and what choosing it does).
Checkbox Card
Section titled “Checkbox Card”A checkbox whose whole card is pressed, with a title, a description and an icon or a price: the add-ons of a plan, the reports a team is sent.
use lurq::ui::{CheckboxCard, CheckboxCardGroup, Orientation, icons};
// Bound to the app's signal, which a press turns.CheckboxCard::new("Analytics").description("Share anonymous usage data.").bind(analytics.clone());
// Cards over one list: those whose values the signal has are checked.CheckboxCardGroup::new(add_ons, [ ("backups", CheckboxCard::new("Backups").icon(icons::SHIELD).price("$4")), ("support", CheckboxCard::new("Priority support").icon(icons::MAIL).price("$20")),]).orientation(Orientation::Horizontal).on_change(|add_ons| println!("{add_ons:?}"));| Builder | |
|---|---|
description(&str) | More of it, under the title in the muted color; what the card is described by to tooling |
icon(name), price(&str) | An icon of 20 before the text; what the choice costs, at the end of the title |
checked(bool) | Whether it is checked. The card does not keep it: the app says so |
bind(Signal<bool>) | Checked while the signal is true, which a press turns: checked and a handler that sets the signal |
on_change(handler) | Called on a press with what the card is to be: checked if it was not. Bound, it is called after the signal is set, and not when the app sets it |
invalid(bool), full_width(bool) | The edge in the destructive color; as wide as what holds it in place of 220 |
mark(element) | An element of the app’s in place of the icon, in the part Icon: a mark in its own colors |
content(element) | An element under the description, in the part Content, 8 under it; a second stands 8 under the first. A press in it presses the card too, unless it stops its press |
disabled_reason(&str) | Disabled for a reason: the reason under the description (part Reason) and to tooling (a11y_disabled_reason), a lock (part Lock) in place of the box or the mark |
loading(bool) | What it chose is under way: no press, dimmed, its box or mark kept, a11y_busy to tooling (state Loading) |
disabled(bool), state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. id is the id of the card |
CheckboxCardGroup<T> | |
|---|---|
new(Signal<Vec<T>>, [(T, CheckboxCard)]) | The cards whose values the signal has are checked; a press adds a value or takes it out |
controlled(checked, [(T, CheckboxCard)], on_change) | The app holds what is checked and is told the whole new set a press asks for (&[T]); what is drawn is what it says next |
on_change(handler) | Called with the whole new set checked (&[T]) after a press, after the signal is set |
orientation(Orientation) | Vertical unless told; Horizontal, side by side, 12 apart and as high as the highest, going on to the next line where there is no room |
label(&str), invalid(bool), disabled(bool) | What the group is called to tooling; every card invalid or disabled |
state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. force draws the card Tab would stop on |
- The card is what is pressed: a click anywhere on it, or Space or Enter while it has the focus. It is the one stop of Tab and the ring of the focus is around it; the box in it is drawn and takes no focus of its own. In a group each card is its own stop.
- Parts:
ChoiceCardPart::Root(what is pressed),Icon,Text,Heading(the title and the price),Title,Price,Description,Content,Reason,Lock. States:ChoiceCardState::Checked(a checkbox card),Selected(a radio card),Invalid,Disabled,FullWidth,Loading. The box is the checkbox’s ownCheckboxPart::BoxandIndicator, resolved from the theme’s checkbox recipe: a theme that restyles a checkbox restyles the card’s box. A group’s parts areChoiceCardGroupPart::RootandItem(laid over each card’s root), its statesChoiceCardGroupState::HorizontalandVertical, one of which is on. A theme’s renderer of either group gets aChoiceCardGroupView: its cards built, inview.cards,view.kind, andview.render(); a theme names the groups without their type (patch_recipe::<RadioCardGroup>), for groups of everyT. - In the design the card is 220 wide, padded 16, in
Backgroundwith the large radius; the text first, the title in 14 and medium over the description 4 under it in 13 ofMutedForeground, and the box 12 after it at the top. Not checked its edge is 1 ofInput; checked, 2 ofPrimary. Under the pointer the edge of a card not checked isRing; an invalid card is edged inDestructive; a disabled one is dimmed. - To what reads the tree (
lurq_snapshotof the MCP server) the card is acheckboxcalled by its title, described by its description, witha11y_checkedsaying whether it is checked; a group is agroup. - In a field a card is invalid where the field is and disabled where the field is, and keeps its title as its name; a group takes the field’s label as its name unless it has one.
- A renderer that draws another card is given a
ChoiceCardView:view.root()is the behavior with the root’s style,view.text(),view.icon()andview.control()the default parts;view.checkedsays whether a checkbox card is checked. The same renderer type serves the radio card, whoseview.selectedsays whether it is selected;view.kindsays which it is.
Radio Card
Section titled “Radio Card”A radio whose whole card is pressed, with a title, a description and an icon or a price: the plan of an account, the density of a list.
use lurq::ui::{RadioCard, RadioCardGroup};
RadioCardGroup::new(density, [ (Density::Comfortable, RadioCard::new("Comfortable").description("Roomy rows, 36px controls.")), (Density::Compact, RadioCard::new("Compact").description("Dense rows, 28px controls.")), (Density::Touch, RadioCard::new("Spacious").description("For touch.").disabled(true)),]);
// One card alone: the app says whether it is selected and is told when it is pressed.RadioCard::new("Team") .price("$12") .selected(plan.get() == Plan::Team) .on_change(move |_| plan.set(Plan::Team));| Builder | |
|---|---|
description(&str), icon(name), price(&str), mark(element), content(element), disabled_reason(&str), loading(bool) | As a checkbox card has them |
selected(bool) | Whether it is the one of several selected: the dot in its mark. The card does not keep it |
on_change(handler) | Called with true on a press while the card is not selected. A press of the one selected calls nothing |
invalid(bool), full_width(bool), disabled(bool), state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a checkbox card has them |
RadioCardGroup<T> | |
|---|---|
new(signal, [(T, RadioCard)]) | The card whose value the signal has is selected; a press of another sets the signal: a Signal<T>, or a Signal<Option<T>> of which None selects none |
controlled(Option<T>, [(T, RadioCard)], on_change) | The app holds the choice, none while it is None, and is told the value (&T) of each other card pressed; what is drawn is what it says next |
on_change(handler) | Called with &T, the value of a card pressed that was not the one selected, after the signal is set |
orientation(Orientation), label(&str), invalid(bool), disabled(bool), state(..), style(..), rules(..), force(..), id, key | As a checkbox card group has them |
- A group is one stop of Tab, at the selected card or the first. The arrow keys move the focus to the next card and select it, Home and End the first and the last, and a disabled card is passed by: the focus group of a radio group,
FocusGroup::both().activate(true).one_stop(true). - Parts and states are a checkbox card’s (
ChoiceCardPart,ChoiceCardState); its mark is the radio’s ownRadioPart::MarkandDot, from the theme’s radio recipe. - In the design it is a checkbox card with the radio’s mark of 16 in place of the box: not selected, an edge of 1 of
Input; selected, 2 ofPrimary, with the dot of 8 in the mark. - To what reads the tree the card is a
radiocalled by its title, described by its description, witha11y_checked; a group is aradiogroup.
Fieldset
Section titled “Fieldset”Fields that go together, under a legend that says what they are: the profile of an account, the address of an order. As a group box, a few options of a desktop dialog under a small legend.
use lurq::ui::{Button, Checkbox, Field, Fieldset, FieldsetVariant, Input};
Fieldset::new("Profile") .description("Shown to people you share a workspace with.") .field(Field::new("Display name", Input::new(name).full_width(true)).required(true)) .field(Field::new("Bio", Input::new(bio).full_width(true)).optional(true)) .child(Button::new("Save profile")) .disabled(locked.get());
// A group box: the legend over a box of what it holds.Fieldset::new("Startup") .variant(FieldsetVariant::GroupBox) .child(Checkbox::new("Open at login").bind(login)) .child(Checkbox::new("Restore windows").bind(restore));| Builder | |
|---|---|
variant(..) | FieldsetVariant::Boxed (the default: the edge around the legend and the fields) or GroupBox (a small legend over a box of what it holds), or a variant the theme’s recipe names |
description(&str) | More of it, 4 under the legend, in the muted color |
field(Field) | Adds a field, made as wide as the fieldset (Field::full_width) |
child(element), children(..) | Adds anything else under what is there: a row of buttons, a group of cards, an error summary |
disabled(bool) | Every control in it takes no input and Tab passes it by; the whole fieldset is dimmed |
full_width(bool) | As wide as what holds it, in place of 400 (250 as a group box) |
state(name, on), style(part, ..), rules(&recipe), id, key | As a field has them |
- What it holds is one under another, 16 apart, and stretched to its width: a field keeps a width of its own unless it is made full width, which
fielddoes. - Parts:
FieldsetPart::Root,Legend(the title over the description),Title,Description,Body(what it holds; a group box’s edge is around it). States:FieldsetState::Disabled,FullWidth. - In the design the fieldset is 400 wide, padded 20, with an edge of 1 of
Borderinside it and the large radius. The legend’s title is 15 and semibold inForeground, its description 13 inMutedForeground. - The group box of the design (
Group Box) is theGroupBoxvariant: 250 wide, the legend’s title 12 and semibold inMutedForeground, and 6 under it a box with an edge of 1 ofBorderand the medium radius, padded 12, what it holds 10 apart. The board gives it no description: one is 12, 2 under the title. It names its group and disables it as the boxed fieldset does. - A disabled fieldset disables its root, and an element that is disabled takes everything in it out of input, whatever it is: a control the app built itself too. The fieldset is dimmed as a whole, so a control in it is not dimmed again by its own disabled state.
- To what reads the tree it is a
groupcalled by its legend and described by its description.
Error Summary
Section titled “Error Summary”What is wrong in a form, at its top, a line for each field with a link to it: what a person reads when a form they sent was not accepted.
use lurq::ui::{ErrorSummary, FieldError};
ErrorSummary::new([ FieldError::new("Display name", "Display name is required").focuses(&name_field), FieldError::new("Email", "Email must include a domain").focuses(&email_field),]);
// From a form's own errors, once a submit of it was attempted (the `form` feature).ErrorSummary::form(&form, [("name", "Display name", &name_field), ("email", "Email", &email_field)]);| Builder | |
|---|---|
new(errors) | A line for each FieldError, in the order given. With none the summary draws nothing |
FieldError::new(label, error) | The field’s label and what is wrong with it, as its field says it. The line shows the error. id and key are the line’s |
error(FieldError), errors(..) | Adds lines after those it has |
FieldError::focuses(&ElementRef) | A press of the line, or Enter or Space on it, focuses the first control under the ref |
form(&FormHandle, [(name, label, &ElementRef)]) | The form’s errors once a submit was attempted: a line for each listed field that has one, in their order, then one for each other field with an error, called by its name and focusing nothing. It reads them as signals: what renders it renders again when they change |
title(&str) | The title in the app’s own words, in place of “2 fields need attention” |
full_width(bool), state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a fieldset has them; force draws every line as under the pointer or focused |
- A line that focuses a field is a stop of Tab, underlined under the pointer, with the ring of the focus around it. One that focuses nothing is read and not pressed.
- Parts:
ErrorSummaryPart::Root,Icon,Text(the title over the lines),Title,Item(a line),Bullet,Error. State:ErrorSummaryState::FullWidth. - In the design the summary is 400 wide, padded 12 and 14, in
DestructiveMutedwith an edge of 1 ofDestructiveinside it and the medium radius. The alert icon of 16 inDestructiveis 10 before the body; the title is 13 and semibold inDestructive, and the lines are 6 apart under it, a dot of 4 inDestructive8 before each message in 13 ofForeground. - To what reads the tree it is an
alertcalled by its title; each line is alinkcalled by the field’s label and its error. - A line focuses its field through
.focuses(&ElementRef), which a button has: a click of it or Enter or Space on it focuses the target. A ref on a column around aFieldwill do: the control is the first thing under it that takes the focus.
Combobox
Section titled “Combobox”A select a person types in, whose list what is typed filters: a framework, a country, an assignee among many.
use lurq::{components::SelectOption, ui::Combobox};
Combobox::new(framework.clone(), [ ("lurq".to_owned(), "lurq"), ("gpui".to_owned(), "GPUI"), ("slint".to_owned(), "Slint"),]).placeholder("Select framework");
// Options an app fetches as a person types: it keeps all it was given.Combobox::new(country.clone(), fetched.get().iter().map(|name| (name.clone(), name.as_str())).collect::<Vec<_>>()) .on_query(move |typed| fetched.set(search(typed))) .filter(|_, _| true) .loading(searching.get());
// A value that is no option's: what is typed becomes the value of a combobox of String.Combobox::new(label.clone(), [SelectOption::new("bug".to_owned(), "bug")]).allow_custom(true);
// One that may hold none, with a cross that takes it away, and Enter that submits what is typed.Combobox::optional(assignee.clone(), people) .clearable(true) .on_submit(|typed| search(typed));| Builder | |
|---|---|
Combobox::new(value, options) | Bound to a Signal<T>: the option with its value is chosen, and choosing another sets it. The options are a select’s: (value, label) or SelectOptions with a detail, a hint, elements before and after the label, a group they start, or disabled |
optional(Signal<Option<T>>, options), controlled(value, options, on_change) | As a select’s: a value that may be none; a value the app holds, whose answer the box shows |
on_change(Fn(&T)) | Called with the new value when a person chooses an option, keeps a value of their own (allow_custom) or clears it: not when the app sets the signal, and not for what is chosen already. Its handler names the type of the value, as a select’s does |
on_submit(Fn(&str)) | Called on Enter with what the box holds, where Enter chooses nothing: the list is closed, or nothing in it is highlighted |
clearable(bool) | A cross at the end of the box, while something is chosen or typed, that takes the value and what is typed away: None of an optional combobox, the empty text of a combobox of String. One of a value that cannot be none has no cross. clear_label(&str) is what tooling calls it, “Clear” |
read_only(bool) | What is chosen is read and not changed: the list does not open, what is typed is not taken, and there is no cross |
placeholder(&str) | What the box says while nothing is typed |
filter(Fn(&str, &str) -> bool) | Which options are shown while something is typed, given the label and what is typed. By default the labels that contain it, without regard to case |
on_query(Fn(&str)) | Called with what the box will hold at each edit: for an app that fetches its options |
loading(bool) | The list ends in a row with a spinner, “Loading results…” (loading_text(&str) says otherwise) |
empty_text(&str) | What the list says while what is typed leaves no option: “No results” |
allow_custom(bool) | What is typed may be no option’s: typing highlights nothing, and Enter or leaving keeps it. A label of an option, in any case, chooses the option; anything else becomes the value of a combobox of String |
query(Signal<String>) | Where the app keeps what is typed, to read or set it. Without one the combobox keeps it while it is in the tree, one for each signal of a value |
size(ComboboxSize) | Sm 32, Md 36 (the default), Lg 40 high, with text of 13, 14, 15 |
invalid(bool), warning(bool), valid(bool) | What is chosen is wrong, doubtful or right: the edge and the ring in the destructive, warning or success color. Of the three, the first that is set is shown |
disabled(bool), full_width(bool), label(&str), name(..) | As a select has them. name is the name of the value in a form: the chosen option’s label |
state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. id is the id of the box; its input has the id with -input after it |
- The box is a select’s with a text input in it, which keeps the focus the whole time. A press anywhere on the box focuses the input and opens the list; typing opens it too and filters it, with the first option that can be chosen highlighted. Down and Up move the highlight, which a row shows as it shows the pointer; Enter chooses; Escape closes the list and a second Escape clears what was typed; Tab chooses nothing, closes the list and goes on.
- Choosing puts the option’s label in the box. While the box shows the chosen label the list opens whole; what is typed otherwise filters it. When the focus leaves, what was typed goes back to the chosen label, unless custom values are allowed. A group keeps its label over the first of its options that what is typed leaves.
- It is a control a field holds (
FieldControl): the field names it, judges it and disables it. - Parts:
ComboboxPart::Trigger(the box),Value(what is typed),Placeholder,Chevron,Panel(the panel of the list),Item,Check,Detail,Hint,Group,Separator(a select’s, by the same names),Status(the row of no results or of loading),Spinner, andClearandClearIcon(the cross ofclearable). States:ComboboxState::Open,Invalid,Warning,Valid,ReadOnly,Disabled,FullWidth; an item’s ownSelectedandDisabledare resolved on its parts. - In the design the box is a select’s: 260 by 36,
Backgroundin an edge of 1 inInput, 6 round, its text 12 in, the placeholder inMutedForeground, two chevrons of 16 at its end; the ring’s color under the pointer and a line of 2 inside it while the focus is in it or the list is open. The list is a select’s: 4 under the box onPopover, 8 round, items of 32 onHighlightunder the pointer or the keys, the chosen one with a check of 16 at its end. The status row is 32 high, 8 in, inMutedForegroundat 13, its spinner 16 inForeground. - Its options and the row that says there are none or that more are loading follow the density as a select’s do; the box is a control and keeps its size.
- It is the engine’s
Selectin its combobox mode (Select::combobox): one implementation of the list, its rows, groups, checks and adornments with the select’s. To what reads the tree (lurq_snapshotof the MCP server) the box is acomboboxwithexpandedwhile its list is open, the input in it atextboxcalled by the combobox’s label, and the list alistboxofoptions witha11y_selected, which says ina11y_activedescendantwhich option the keys are on. - A renderer that draws another combobox has
view.select_style(),view.input()(the text input, with what leaving it and Enter do),view.clear(),view.chevron(),view.status(),view.query(),view.shown()(the labels the list shows) andview.select(style, trigger), which builds the combobox and callstriggerwith aSelectTriggerStatewhoseinputis the input to place.
Multi Select
Section titled “Multi Select”Several values chosen from a list that what is typed filters, held as tags in the box: the labels of an issue, the people a review goes to.
use lurq::ui::MultiSelect;
MultiSelect::new(languages.clone(), [ ("rust".to_owned(), "Rust"), ("wgsl".to_owned(), "WGSL"), ("typescript".to_owned(), "TypeScript"), ("swift".to_owned(), "Swift"),]).placeholder("Select languages").max_shown(3).clearable(true).on_change(|languages: &[String]| save(languages));| Builder | |
|---|---|
MultiSelect::new(value, options) | Bound to a Signal<Vec<T>>: the options with its values are chosen, shown as tags in the order they were chosen; choosing one adds its value, or takes it out. The options are a select’s |
controlled(values, options, on_change) | The app holds the values: a change is told to on_change with the whole new set, and the box shows what the app answers with. A multi select is the multiple of a select by what it is, so these are its own new and controlled, where a component that holds one value or any number has multiple and controlled_multiple |
on_change(Fn(&[T])) | Called with the whole new set when a person chooses an option, takes one back or away, or clears them: not when the app sets the signal. Its handler names the type of the values, on_change(|languages: &[String]| ..) |
read_only(bool) | What is chosen is read and not changed: the list does not open, what is typed is not taken, the tags have no cross and there is no clear control |
placeholder(&str) | What the box says while nothing is chosen and nothing is typed |
max_shown(usize) | How many tags the box shows: the rest are one tag that counts them, “+3” |
clearable(bool) | A cross at the end of the box, while something is chosen, that takes every value away. clear_label(&str) is what tooling calls it, “Clear” |
filter(..), on_query(..), loading(bool), loading_text(&str), empty_text(&str), query(..) | As a combobox has them |
size(MultiSelectSize) | Sm 32, Md 36, Lg 40 high at least, with tags of 20, 24, 28 |
invalid, warning, valid, disabled, full_width, label, name, state, style, rules, force, id, key | As a combobox has them. A disabled one keeps its tags and takes none away; full_width is in place of 280 |
- The box holds the chosen values as tags (tags of
TagShape::Pill), and a text input after them, which keeps the focus while the list is open. The tags go on to the next line where they do not fit, and the box grows with them. - Typing opens the list and filters it; Down and Up move the highlight; Enter or a press chooses an option or takes it back, and the list stays open while one chooses; a choice clears what was typed, and the list shows every option again. A tag’s cross takes its value away, and so does Backspace in the empty input, the last one’s. Escape closes the list and a second Escape clears what was typed; Tab goes on, and what was typed is cleared when the focus leaves. A press of a tag or of the clear control does not open the list.
- The input is the one stop of Tab, as a token input’s is: the tags are reached from it. With nothing typed, Left goes onto the last tag, drawn as its cross is when focused, and on to the ones before; Right goes back towards the input; Backspace or Delete takes away the tag the arrows are on, and they stay on the tag that takes its place. Typing leaves the tags.
- It is a control a field holds.
- Parts: a combobox’s, by the same names, and
MultiSelectPart::Check(the box before a chosen option),CheckIcon,Unchecked(the box before one that is not),Tags(the lines of the tags and the input: its gap),TagandTagLabel(what is laid over a tag’s root and label),ClearandClearIcon. Its states and sizes are a combobox’s:MultiSelectStateisComboboxState,MultiSelectSizeisComboboxSize. - In the design the box is a select’s, 280 wide and at least 36 high, padded 6 at its start, 10 at its end and 6 over and under, a chevron down of 16 at its end. A tag is 24 high on
Secondary, 4 round, padded 8 before its text of 13 inSecondaryForegroundand 6 after its cross of 12 inMutedForeground; the tags are 6 apart, across and down, and what is typed keeps 48 on their line. The list is a select’s, with a box of 16 before each option, 8 before its label, 4 round:Backgroundin an edge ofInput, and, chosen,Primarywith a check of 12 inPrimaryForeground. - Its options follow the density as a select’s do.
- It is the engine’s multiple
Selectin its combobox mode. To what reads the tree it is acomboboxwithexpanded, its list alistboxofoptions witha11y_selected, and each tag’s cross abuttoncalled “Remove” and the tag’s text; the clear control is abuttoncalled “Clear”, or itsclear_label. - A renderer that draws another multi select has
view.select_style(),view.input(),view.tags(),view.tag_rules(),view.clear(),view.chevron(),view.status(),view.chosen(),view.shown(),view.query()andview.select(style, trigger).
Cascader
Section titled “Cascader”A select whose options are a tree shown as columns that open one after the other, as a menu of submenus does: a place by its continent, its country and its city, a category of a catalogue, a setting by its section.
use lurq::ui::{Cascader, TreeItem};
// city: Signal<Option<&str>>: one or none, of the cities alone.Cascader::optional(city, [ TreeItem::new("asia", "Asia").items([TreeItem::new("japan", "Japan").item(TreeItem::new("tokyo", "Tokyo"))]), TreeItem::new("europe", "Europe").items([ TreeItem::new("ukraine", "Ukraine").items([TreeItem::new("kyiv", "Kyiv"), TreeItem::new("lviv", "Lviv")]), TreeItem::new("poland", "Poland").item(TreeItem::new("warsaw", "Warsaw")), ]),]).label("Place").placeholder("Select a city").clearable(true).mount(ctx);
// A continent or a country may be chosen too, and the columns open under the pointer.Cascader::optional(region, items).leaves_only(false).open_on_hover(true).mount(ctx);
// Held by the app, which is told each choice.Cascader::controlled(app.city(), items, |city| app.set_city(*city));| Builder | |
|---|---|
new(value, items), optional(value, items) | The tree’s items (TreeItem<T>, a tree view’s) and what is chosen of them, bound to a Signal<T> or a Signal<Option<T>>. A value is one item’s: the trigger says the path down to it |
controlled(value, items, on_change), controlled_optional(..) | The same held by the app, which is told on_change(&T) or on_change(&Option<T>) and shows what it gives back |
on_change(handler) | Told what is chosen after a choice a person makes, after the signal is set; not for the option chosen already, nor when the app sets the signal. The cascader is Cascader<T, T> or Cascader<T, Option<T>>, so a handler of another type does not compile |
leaves_only(bool) | Whether only an option that holds nothing is chosen, as the board’s cascader has it (it is unless told otherwise). Without it a press or Enter chooses any option, and a choice of one that holds others leaves the panel open on its column |
open_on_hover(bool) | The pointer on an option that holds others opens its column, as a submenu opens, in place of a press. A press opens it either way |
on_load(handler) | Told an item marked lazy that holds nothing yet as its column opens: where the app brings its children. The column has a spinner until they come |
open(Signal<bool>) | Whether the panel is open, where the app keeps it. on_open_change(bool) hears each change a person makes, a choice too; on_dismiss() Escape and a press outside, before it |
path(bool), separator_text(&str) | The trigger says the whole path to what is chosen, Europe / Ukraine / Kyiv (it does unless told otherwise), or its label alone; and what stands between the steps, " / " |
placeholder(&str), size(CascaderSize), invalid, warning, valid, read_only, disabled, full_width, name | As a select has them. A read only one and a disabled one do not open |
clearable(bool), clear_label(&str) | A cross before the chevron, while something is chosen, that takes it away, of a cascader that may hold none; and what it is called, “Clear” |
empty_text(&str), loading_label(&str) | What the panel says where there are no items, “No options”; what the spinner of a column on its way is called, “Loading” |
locale(&Locale) | The words it speaks in, the name of its cross, what an empty panel says and what a spinner is called, in place of the app’s (App::set_locale(Locale::for_tag("uk")), English where it set none), whose words are Locale::input. A word told by itself (clear_label, empty_text, loading_label) stays; the mark between the steps is no word |
label(&str), panel_label(&str) | What the cascader is called to what reads the tree, and its panel and its columns in place of that |
placement, offset, collision, inline, dismiss_on_escape, dismiss_on_outside_press | As a popover has them: the panel is one |
state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. id is the trigger’s; the panel has it with -panel, the columns with -columns (each column that, -column- and its place), the cross with -clear |
mount(ctx) | In place of converting it: the cascader keeps whether it is open, the trigger the focus goes back to and the columns open in it |
- It is built of what is there already: its trigger is a select’s box (the same recipe, sizes, ring, judgments and fluid form in a field), the one a tree select has, its panel a popover and what the panel holds a column view, with a column view’s columns, options, chevrons and keys. What a
TreeItemhas, it has here:icon,disabled,lazy,trailing. A tree select is its sibling for a tree shown in one column, of which any number may be chosen. - A press, Enter, Space, Down or Up on the trigger opens the panel with the columns of the path to what is chosen open, and the focus on it, or on the first option. A press of an option that holds others opens its column; a press of one that holds nothing chooses it and closes the panel, and the panel closes first and the handler is told after, so a handler that opens a dialog keeps its focus. Up and Down go through a column and open the column of the option they reach, Home and End go to its ends, Right goes into what an option holds and Left back to the option the column is of, a letter to the next option that starts with it; Enter on an option that holds nothing chooses it, on one that holds others goes into it. Moving chooses nothing.
- The focus goes back to the trigger on every way out of the panel: a choice, Escape, a press of the trigger. A press outside closes it and leaves the focus where the press put it. Opened again, the panel is on what is chosen, not on where it was left.
- The panel is as wide as the columns open in it, each 124, and as high as the longest of them, up to 280, past which a column scrolls; where the window is narrower than the columns they scroll sideways.
- A cascader that is only built keeps nothing: converted into an element it is the still form of itself, which opens only where the app holds
open. Mounted (mount(ctx), or by a field that is mounted), it keeps whether it is open, its trigger and the path open in its columns. - The board draws a cascader of one: there is no cascader of any number, and no search over the paths, which the board does not draw.
- To what reads the tree the trigger is a
comboboxwitha11y_haspopuplistbox,a11y_expanded,a11y_value(the path it says),a11y_invalidanda11y_readonlywhere they hold; the panel adialog, each column alistboxcalled by the option it is of, and each option anoptionthat saysa11y_selectedwhile it is on the path open,a11y_expandedwhere it holds others,a11y_level,a11y_posinsetanda11y_setsize. - Parts:
CascaderPart::Trigger,Value,Placeholder,Chevron,Clear,ClearIcon(a select’s and a tree select’s),Panel(laid over the popover’s panel),Columns(laid over the column view’s box: its greatest height),Column,Option,OptionIcon,OptionLabelandOptionChevron(laid over the column view’s column, item, icon, label and chevron), andEmpty. States: a select’s,CascaderState::Open,Invalid,Warning,Valid,ReadOnly,Disabled,FullWidth,Fluid, andSelected, resolved on the parts of an option on the path open. - In the design the trigger is 260 by 36 on
Backgroundin an edge of 1 inInput,radius-md, its path 12 from its edge in the body’s type and a chevron of 16 inMutedForeground8 after it. The panel is 4 under it onPopoverin an edge of 1 inBorder,radius-lg, with the popover’s shadow, and holds the columns with no room around them: each 124 wide, padded 4, with a line of 1 inBorderat its end but the last’s. An option is 30 high (22, 38 and 42 at the compact, comfortable and touch densities), 8 in,radius-sm, its label at 13 inForeground, and where it holds others a chevron of 14 inMutedForeground4 after it. The options on the path are onHighlightwith their labels at 500, the last as the others; under the pointer and held down an option has the veils of those states, and the focus from the keyboard is a ring of 2 inRinginside it. - A theme’s renderer is given
CascaderView:view.text(what the trigger says),view.trigger()(the behavior with the trigger’s style),view.value(),view.clear(),view.chevron(),view.content(),view.panel()andview.render(). It is set forCascader<T>of anyT.
Tree Select
Section titled “Tree Select”A select whose options are a tree: a file of a project, a category of a catalogue, the folders a search looks in.
use lurq::ui::{TreeItem, TreeSelect};
// file: Signal<Option<&str>>: one or none, of the files alone.TreeSelect::optional(file, [ TreeItem::folder("crates", "crates").items([ TreeItem::folder("lurq", "lurq").items([ TreeItem::file("lib.rs", "lib.rs"), TreeItem::file("theme.rs", "theme.rs"), ]), ]), TreeItem::file("Cargo.toml", "Cargo.toml"),]).label("File").placeholder("Select a file").leaves_only(true).clearable(true).mount(ctx);
// Any number: a press adds a row or takes it out, and the panel stays open.TreeSelect::multiple(folders, items).max_shown(2).mount(ctx);
// Held by the app, which is told each choice.TreeSelect::controlled(app.file(), items, |file| app.open(file));| Builder | |
|---|---|
new(value, items), optional(value, items), multiple(values, items) | The tree’s items (TreeItem<T>, a tree view’s) and what is chosen of them, bound to a Signal<T>, a Signal<Option<T>> or a Signal<Vec<T>> |
controlled(value, items, on_change), controlled_optional(..), controlled_multiple(..) | The same held by the app, which is told on_change(&T), on_change(&Option<T>) or on_change(&[T]) and shows what it gives back |
on_change(handler) | Told what is chosen after a choice a person makes, after the signal is set; not for the row chosen already, nor when the app sets the signal. The select is TreeSelect<T, T>, TreeSelect<T, Option<T>> or TreeSelect<T, [T]>, so a handler of another type does not compile |
open(Signal<bool>) | Whether the panel is open, where the app keeps it. on_open_change(bool) hears each change a person makes, a choice too; on_dismiss() Escape and a press outside, before it |
branches(Signal<Vec<T>>), branches_controlled(open, on_branch_change) | The branches of the tree that are open, where the app keeps them. on_branch_change(&value, open) hears each one a press or a key opens or closes: where a lazy item’s children are brought |
leaves_only(bool) | A press of a row that holds others opens or closes it in place of choosing it: only what holds nothing is chosen |
path(bool), separator_text(&str) | The trigger of a select of one says the whole path to what is chosen, crates / lurq / lib.rs (it does unless told otherwise), or its label alone; and what stands between the steps, " / " |
max_shown(n) | How many labels the trigger of a select of any number says before it counts the rest, lib.rs, theme.rs +2 |
placeholder(&str), size(TreeSelectSize), invalid, warning, valid, read_only, disabled, full_width, name | As a select has them. A read only one and a disabled one do not open; a full width one’s panel is as wide as it is |
clearable(bool), clear_label(&str) | A cross before the chevron, while something is chosen, that takes it away, of a select that may hold none; and what it is called, “Clear” |
empty_text(&str) | What the panel says where the tree has no items: “No options” |
label(&str), panel_label(&str) | What the select is called to what reads the tree, and its panel and its tree in place of that |
placement, offset, collision, inline, dismiss_on_escape, dismiss_on_outside_press | As a popover has them: the panel is one |
state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. id is the trigger’s; the panel has it with -panel, the tree with -tree, the cross with -clear |
mount(ctx) | In place of converting it: the select keeps whether it is open, the trigger the focus goes back to and which branches are open |
- It is built of what is there already: its trigger is a select’s box (the same recipe, sizes, ring and judgments), its panel a popover and what the panel holds a tree view, with a tree’s rows, icons, chevrons and keys. What a
TreeItemhas, it has here:disabled,lazy,trailing. - A press, Enter, Space, Down or Up on the trigger opens the panel, and the focus goes to the chosen row, or the first. Up and Down move through the rows, Right and Left open, close and go in and out, a letter goes to the next row that starts with it. Of one, a press of a row or Space chooses it, Enter does on a row that holds nothing (on one that holds others it opens or closes it), and the panel closes first and the handler is told after, so a handler that opens a dialog keeps its focus. Of any number, a press of a row or Space adds it or takes it out, a press with Shift chooses the rows from the last chosen to it, and the panel stays open.
- The focus goes back to the trigger on every way out of the panel: a choice, Escape, a press of the trigger. A press outside closes it and leaves the focus where the press put it. Tab in the panel leaves the tree, which is one stop.
- A select that is only built keeps nothing: converted into an element it is the still form of itself, which opens only where the app holds
open. Mounted (mount(ctx), or by a field that is mounted), it keeps whether it is open, its trigger and which branches are open. As the panel opens, the branches the chosen rows are in open, so it opens on what is chosen; while it is open nothing opens or closes but by a person, so a row taken out of what is chosen stays under the focus. - A select of any number has no checkboxes: the board draws none, and its rows are a tree’s, in the highlight while they are chosen.
- A cascader is its sibling for a tree shown as columns that open one after the other, of which one is chosen. Its trigger is the same.
- To what reads the tree the trigger is a
comboboxwitha11y_haspopuptree,a11y_expanded,a11y_value(what it says),a11y_invalid,a11y_readonlyanda11y_multiselectablewhere they hold; the panel adialogand what it holds atreeoftreeitems, called by the select’s label. - Parts:
TreeSelectPart::Trigger,Value,Placeholder,Chevron,Clear,ClearIcon,Panel(laid over the popover’s panel),Tree(its greatest height, past which the tree scrolls),Row,RowIconandRowLabel(laid over the tree view’s row, icon and label) andEmpty. States: a select’s,TreeSelectState::Open,Invalid,Warning,Valid,ReadOnly,Disabled,FullWidth. - In the design the trigger is 260 by 36 on
Backgroundin an edge of 1 inInput,radius-md, its text 12 from its edge in the body’s type and a chevron of 16 inMutedForeground8 after it. The panel is 4 under it, 260 wide onPopoverin an edge of 1 inBorder,radius-lg, with the popover’s shadow and 8 of padding around the tree. The tree scrolls past 280. - A theme’s renderer is given
TreeSelectView:view.text(what the trigger says),view.trigger()(the behavior with the trigger’s style),view.value(),view.clear(),view.chevron(),view.panel()andview.render(). It is set forTreeSelect<T>of anyT.
Transfer
Section titled “Transfer”Two lists side by side, and the buttons between them that move the items checked in one to the other: the features a build has, the columns a table shows, the members of a group.
use lurq::ui::Transfer;
// enabled: Signal<Vec<&str>>: the values of the items on the right.Transfer::new(enabled, [ ("canvas", "canvas"), ("svg", "svg"), ("router", "router"), ("wgpu", "wgpu"), ("winit", "winit"),]).source_title("Available").target_title("Enabled").label("Features").mount(ctx);
// Held by the app, which is told each new value.Transfer::controlled(app.features(), items, |features| app.set_features(features));| Builder | |
|---|---|
new(value, items) | Bound to a Signal<Vec<T>>: the items of its values are on the right, in the order they came there, and a move sets it. The items are a listbox’s options: (value, label) or a SelectOption with disabled, detail, hint, leading, trailing. The left list has the rest, in the order of the items |
controlled(value, items, on_change) | The same held by the app, which is told the whole value a move asks for and shows what it gives back |
on_change(handler) | Told the whole new value, &[T], after a move, after the signal is set; not when the app sets the signal. A second handler is called after the first |
checked(Signal<Vec<T>>), checked_controlled(checked, on_checked_change), on_checked_change(handler) | What is checked in either list, where the app keeps it (without it a mounted transfer keeps it), and what hears each change a press, a key or a move makes |
source_title(&str), target_title(&str) | What the lists are called, in their headers and to what reads the tree: “Available” and “Selected” |
count_text(Fn(checked, total) -> String) | What a header says of how many of its items are checked, of how many: 1/3 |
select_all_label(&str), add_label(&str), remove_label(&str) | What the header’s checkbox and the two buttons are called to what reads the tree: “Select all”, “Add”, “Remove” |
empty_text(&str) | What a list with no items says: “No items” |
locale(&Locale) | The words it speaks in, its lists’ titles, the names of its checkboxes and buttons and what an empty list says, in place of the app’s (App::set_locale(Locale::for_tag("uk")), English where it set none), whose words are Locale::input. A word told by itself (source_title, add_label and the others) stays; the count is no word |
label(&str), disabled(bool), density(Density) | What the transfer is called, to what reads the tree; nothing in it takes input; how high an item is, whatever the theme’s density |
state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. id is the root’s; the lists’ items have it with -source and -target (each item that and - and its place), their headers’ checkboxes with -source-all and -target-all, the buttons with -add and -remove |
mount(ctx) | The transfer keeps what is checked, measures its room before it is painted and finds its narrow form there, and a list of more than two hundred items builds only those near its view. Converting it into an element declares the same component; build(theme) is the still form, wide only |
- Each list is a listbox of any number with
checkboxes(true): a press of an item checks it or unchecks it and leaves the rest, a press with Shift checks the range from the last one checked and keeps what else is, and the keys are a listbox’s: one stop of Tab, Up and Down, Home and End, the page keys, a letter, Space to check, Shift with the keys to check a range, Ctrl+A to check every item that can be. A disabled item is faded, is not checked and does not move. - The checkbox in a list’s header checks every item of the list that can be checked, or none, and is half checked while some are; it is disabled while none can be. The count beside it says how many are checked, of how many items the list has.
- The primary button, with a chevron to the right, moves what is checked on the left to the end of the right, in the order of the items; the outline one, with a chevron to the left, moves what is checked on the right back. Each is disabled while its list has nothing checked. A move sets the value and tells
on_change, then takes what moved out of what is checked. The focus stays on the button that was pressed. - Its narrow form is chosen by its own room: mounted, it measures the room before the frame is painted, and where the two lists and the buttons do not fit side by side the lists are as wide as the room, one over the other, and the buttons are side by side between them with their chevrons turned down and up. The first frame is the settled one. Converted into an element (
.child(transfer)) it is that same live component, asmount(ctx)makes it;build(theme)is its still form, side by side whatever its room, with nothing checked unless the app holds what is. - A list scrolls past 264, eight items; one of more than two hundred items, in a mounted transfer, is a listbox mounted in a virtual list, which builds only the items near its view and which the keys reach every item of.
- To what reads the tree it is a
groupcalled by its label, each list alistboxthat isa11y_multiselectable, called by its title, ofoptions that saya11y_checkedanda11y_selected; the header’s checkbox is acheckboxthat saysmixedwhile some are checked, and the buttons arebuttons called “Add” and “Remove”. - Parts:
TransferPart::Root(the room between the lists and the buttons),List,Header,Title,Count,Items(laid over the listbox’s box: its greatest height, past which the items scroll),ItemandItemLabel(laid over the listbox’s option and label),EmptyandActions. States:TransferState::DisabledandStacked. - In the design a list is 190 wide on
Backgroundin an edge of 1 inBorder,radius-lg, 12 from the buttons, the two lists in the middle of each other’s height. Its header is 36 high onMutedwith a line of 1 inBorderunder it, 12 in from its sides: a checkbox, the title in the body’s type at 13 and 500 inForeground, and the count in the mono type at 11 inMutedForeground, 8 apart. Its items are 4 in from its top and bottom, each 32 high (24, 40 and 44 at the compact, comfortable and touch densities), 12 in, a checkbox and the label at 13, 8 apart; under the pointer an item is onMuted, and the focus from the keyboard is a ring of 2 inRinginside it. The buttons are 32 square, 8 apart. A list with no items says so at 13 inMutedForeground, 12 in. - A theme’s renderer is given
TransferView:view.sourceandview.target(each aTransferListwith its title, its count, how many are checked andlist.header(),list.select_all(),list.render(items)),view.button(to_target),view.actions(),view.stackedandview.render(). It is set forTransfer<T>of anyT.
Token Input
Section titled “Token Input”A box that holds a list as tokens, with what is being typed after them: tags, recipients. Or a text in which the app finds its tokens: the variables of a template.
use lurq::ui::{TagVariant, Token, TokenInput};
// Tags, a list: Enter, a comma or a space makes a token of what is typed.// tags: Signal<Vec<String>>TokenInput::list(tags.clone()) .separators([',', ' ']) .unique(true) .placeholder("Add tag") .on_change(|tags| save(tags));
// A template, a text on rows: its variables are tokens with no cross.// template: Signal<String>TokenInput::new(template.clone()) .rows(2, 6) .find_tokens(|text| { text .match_indices("{{name}}") .map(|(at, name)| Token::new(at..at + name.len()).variant(TagVariant::Info).removable(false)) .collect() });| Builder | |
|---|---|
list(Signal<Vec<String>>) | A list: each item is a token. What is typed is the draft, which is no part of the list until it is made an item. What the app sets on the list is shown |
separators(chars) | The characters that make an item of the draft, as Enter does: a comma by default. A pasted list is split at them, at line breaks and at tabs; an item cannot hold one |
query(Signal<String>) | The draft, what is typed and is no item yet: the query read for suggestions, as a combobox’s is, and what the app sets on it is what the input shows after its tokens |
unique(bool) | An item the list already has is not added again; what was typed is dropped |
commit_on_blur(bool) | The draft becomes an item when the focus leaves, in place of staying typed |
dress_token(impl Fn(&str, Token) -> Token) | Dresses the token of each item of a list: a variant by what the item is, or no cross |
on_change(impl Fn(&[String])) | Called with the list when a person changed it: an item made of the draft, pasted, or taken away |
on_query(impl Fn(&str)) | Called with the draft, the query, when a person changed it; not when the app sets query |
new(Signal<String>) | A text, tokens and all, where the text around the tokens is the value too; what is typed is set on it, and what the app sets on it is shown |
find_tokens(impl Fn(&str) -> Vec<Token>) | How the app finds its tokens in a text, called in every render. Tokens that overlap one before them, hold a line break or are not on characters are left out. Not asked over a list |
Token::new(range) | A token over a byte range of the text: atomic and removable by default |
Token::variant(name) | A TagVariant (Neutral, Info, Success, Warning, Destructive), MENTION, or a variant the theme’s recipe names |
Token::removable(bool) | The cross at its end, which a click takes it away by |
Token::atomic(bool) | One thing to the caret (the default), or text drawn as a token that the caret goes into |
Token::separated(text, char) | The items of a list typed with a separator: each item with a separator after it |
rows(min, max) | Text on several rows, between the two counts, tokens wrapping with the words; one line without it |
placeholder(&str) | What it says while it is empty |
size(TokenInputSize) | Sm 32, Md 36 (the default), Lg 40 high, with tokens of 20, 24 and 28 |
invalid(bool), warning(bool), valid(bool) | The edge in the destructive, warning or success color, as an input’s |
read_only(bool) | Focused, selected and copied, not changed; its tokens have no cross |
full_width(bool) | As wide as what holds it, in place of 260 |
on_input(handler) | Called before an edit, taking a token away by its cross too; prevent_default() refuses it |
controller(TextInputController) | Kept by the app: reads the selection and puts text at it, a token chosen from a picker |
label(&str), name(..), disabled(bool), state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As an input has them. id is the id of the control |
- Over a list (
TokenInput::list) the tokens and what is typed are two things. The list holds the items and nothing else; the draft is the text after the tokens, and it is in no item until Enter or a separator makes one of it, trimmed. A token’s cross takes its item out of the list; Backspace right after a token selects it and the next takes it out. What is typed with the caret among the tokens goes to the draft, which is always after them, and typing over a selected token replaces it with a draft.on_changehears the list andon_querythe draft;on_inputstill hears every edit, with the text the input keeps the list as. - The input keeps that text itself, for as long as it is in the tree, by the signal of the list: each item with a
narrow space (U+2005) after it, which is the room between two tokens and where a row wraps, then the draft. It is
what a
TokenInputViewhas astext, what is copied from the input and what tooling reads as its value. A list whose signal is made anew in every render starts with no draft in every render: keep the signal. - Over a text (
TokenInput::new) it is the engine’sTextInputwithTextInput::tokens: what it holds is text, and a token is a range of that text the app’s function finds in every render, so an edit that changes a token’s text makes it what the function then says of it. Copying, pasting, undo, a form and tooling see the text: to what reads the tree it is atextboxwhose value is the text, each token as its own words. - A token is atomic: Left and Right go past it whole, a click selects all of it, Backspace after it selects it and the
next deletes it. A click on its cross deletes it with the space after it, as one edit
on_inputhears and undo brings back. WithToken::separated, deleting the space after the last token makes it text again, to be edited. - The box is an input’s (one line) or, with
rows, a textarea’s: the same sizes, judgments, read only and disabled, and a field names and judges it as it does an input. - Parts:
TokenInputPart::Root(its width),Control(the box: edge, fill, height, padding, the type of the text),Placeholder,Token(fill, edge, radius, height, the room before the text and after the cross, and the gap between them),TokenLabel(the token’s type and color),TokenIcon(the cross: its side and color). States:TokenInputState::Invalid,Warning,Valid,ReadOnly,Disabled,FullWidth,Multiline, and a token’s ownHoveredandSelected. A token’s parts are resolved with its variant and its state as the case, so a recipe styles a variant’s tokens with.variant(..)and their looks with.state(TokenInputState::Hovered, ..). - It is a text input in both forms, always bound to a signal: it has no
controlledform. ATokenis a range of the text, not an element: it has noidorkey. - In the design the box is 260 by 36, an input’s, padded 6 at its sides. A token is 24 high,
Secondary,radius-sm, 8 before its text and 6 after its cross; its text is 13 inSecondaryForegroundand its cross 12 inMutedForeground, 4 after the text. A colored variant is in the muted fill of its color with its text and cross in the color, as a tag is. Under the pointer a token isSecondaryHover(a colored one keeps its fill) and its crossForeground; covered by the selection it isPrimarywith its text and cross inPrimaryForeground. On rows the box is padded 6 down too and its lines are 28 high, so a token has room around it. - A renderer is given a
TokenInputView:view.tokens(what was found),view.control()(the engine’s input with the tokens drawn in the recipe’s style),view.token_style(recipe, cross)(how the engine draws a token of a resolved case),view.root(control).
Mentions
Section titled “Mentions”Text in which a trigger opens a list of what can be mentioned, and what is chosen stands as a token: a comment, a message, a prompt.
use lurq::ui::{Avatar, Mention, Mentions, MentionsController, icons};
// Kept by the app, with the value, from one render to the next.let mentions = MentionsController::new();
Mentions::new(comment.clone(), &mentions) .trigger('@', vec![ Mention::new("Ivan Zaida").avatar(Avatar::new("Ivan Zaida")), Mention::new("Ivy Chen").avatar(Avatar::new("Ivy Chen")), ]) .trigger('#', |typed: &str| teams_starting_with(typed)) .on_mention(|text| println!("mentioned {text}")) .placeholder("Write a comment");| Builder | |
|---|---|
new(Signal<String>, &MentionsController) | The text, and what the field keeps between renders: the app keeps both |
trigger(char, options) | What a character at the start of a word offers: a Vec<Mention>, narrowed to the offers whose label or text has what is typed after it (without regard to case), or a function of what is typed. At most 8 are shown |
Mention::new(label) | An offer: text(&str) is what it puts in the field (the trigger and the label by default), avatar(Avatar) or icon(name) before its label; disabled(bool) shows it dimmed and leaves it to no choice, id and key are its row’s |
on_mention(handler) | Called with the text of an offer as it is chosen |
find_tokens(..) | Other tokens of the app’s in the text, as a token input finds them |
rows(min, max) | 2 and 8 unless told |
full_width(bool) | As wide as what holds it, in place of 280 |
input_rules(&recipe) | Rules laid over the token input it is |
size(MentionsSize) | An input’s sizes (MentionsSize is TextBoxSize): the type of its text and mentions, 13, 14 or 15 |
placeholder, invalid, warning, valid, read_only, disabled, label, name, on_input, state, style, rules, force, id, key | As a token input has them |
- Typing a trigger at the start of the text or after a space opens the list under it while it offers something. Up and Down move the offer that Enter (or Tab) chooses, a click chooses one, the pointer moves the active one, and Escape puts the list away while the caret stays in that word, so that Enter is a new line again. A disabled offer is passed by: Up and Down go over it, the pointer does not light it, and a click on it chooses nothing. The keys stay in the field the whole time: the list takes no focus, and a press on it does not blur the field.
- Choosing puts the offer’s text and a space in place of the trigger and what was typed, as one edit through
on_input. From then on that text is a mention wherever it stands as a word of its own: a token of the variantMENTION, atomic, with no cross.MentionsController::mention(text)makes a text a mention without choosing it (what a message loaded with mentions has), andmentioned()lists them. MentionsControllerholds the field’sTextInputController(input()), the active offer, the trigger Escape put away and the mentions; a builder has noCtx, and these must outlive a render, as the engine’s controller does.- It is a token input on rows: to tooling a
textboxwhose value is the text with each mention as the offer’s text, witha11y_haspopuplistboxanda11y_expanded; the list is alistboxofoptions, the active onea11y_selected. - Parts:
MentionsPart::Root,Control(laid over the token input’s control: its padding, line and least height),Panel(the list that floats under the trigger),Item,ItemAvatar,ItemIcon,ItemLabel; the mentions themselves are the token input’s parts in the variantMENTION. States:MentionsState::Open, and an offer’s ownHighlighted(the one Enter chooses) andDisabled. - A renderer that draws another field has
view.control(),view.item(index, offer)andview.panel(). - In the design the box is 280 wide and at least 64 high, padded 12 across and 8 down, its text 14 with lines of 1.5.
The list hangs 4 under the trigger: 220 wide,
Popover,radius-lg, an edge of 1 inBorder, the medium shadow, padded 4. An offer is 36 high, padded 8,radius-sm, an avatar of 24 (or an icon of 16 inMutedForeground) 8 before its label in the body’s type; the active one, and the one under the pointer, are onHighlight. A mention is in the text’s type onInfoMuted, its text inInfo, 20 high and padded 4.
Rich Text Editor
Section titled “Rich Text Editor”Formatted text typed into a box, under a bar of the tools that format it: a comment, release notes, the body of an
article, with pictures among its words. It comes with the markdown feature.
use lurq::{components::RichText, ui::{RichTextEditor, RichTextTool}};
// notes: Signal<RichText>, kept by the app. The document reads from Markdown and writes it.let notes = ctx.signal(RichText::from_markdown("## Release notes\n\nBackdrop blur **follows clips**.\n\n- Faster shaping"));RichTextEditor::new(notes.clone()) .placeholder("Write the release notes") .on_change(|document| println!("{}", document.to_markdown())) .mount(ctx);
// A comment box: a few tools, no footer.RichTextEditor::new(comment.clone()) .tools([RichTextTool::Bold, RichTextTool::Italic, RichTextTool::Bullet, RichTextTool::Link]) .footer(false) .rows(3, 8) .mount(ctx);
// Held by the app: it is told each change, and the editor shows what the app answers with.RichTextEditor::controlled(document.clone(), move |changed| store.set(changed.clone())).mount(ctx);
// Pictures. In `create`: the app's handle on the editor, and the system's dialog for a file.let editor = RichTextController::new();let window = ctx.window();let choose = ctx.future_action(move |()| { FileDialog::new().title("Insert a picture").filter("Pictures", &["png", "jpg", "jpeg", "gif", "webp"]).pick_result(&window)});// In `render`: the image tool opens the dialog, and the file a person chose goes in at the caret.if let Some(path) = chosen_path(&choose.state().get()) { editor.insert_picture(&path, "A picture");}let open = choose.clone();RichTextEditor::new(notes.clone()) .controller(&editor) .on_image(move || open.run(())) .mount(ctx);chosen_path is the app’s: the path of the first file of a fulfilled state, taken once (see
Files a person gives).
| Builder | |
|---|---|
new(Signal<RichText>) | The document. Each change is written into the signal, and what the app writes there shows |
controlled(value, on_change) | A document the app holds: each change is told to on_change, and a change the app does not take is taken back |
on_change(handler) | Called with the &RichText after each change a person makes: typing, a tool, a key, undo. The signal is set first. Not when the app sets it |
placeholder(&str) | What the box shows while it holds nothing |
rows(min, max) | The rows of body text the box shows at least, and at most before its text scrolls inside it: 6 and 16 unless told (RICH_TEXT_MIN_ROWS, RICH_TEXT_MAX_ROWS) |
tools(tools) | The RichTextTools of the bar, in order: Style, Bold, Italic, Underline, Strikethrough, Bullet, Ordered, Quote, Code, Link, Image, Undo, Redo. A line stands between two groups and the history is at the bar’s end. All but Image unless told (RichTextTool::DEFAULT) |
toolbar(bool), footer(bool) | Whether it has its bar, and the row under the box that says Markdown shortcuts are on and counts the words: both unless told |
markdown_shortcuts(bool) | Whether Markdown typed becomes what it says: on unless told |
on_link_click(handler) | Called with a link’s target when it is clicked with Ctrl held (Cmd on a Mac): the app opens it |
on_image(handler) | What the image tool does; with it the bar has the tool. The app asks for a picture, with the system’s dialog for a file or a panel of its own, and puts it in with the controller’s insert_picture |
on_paste_image(Fn(&ClipboardImage) -> Option<String>) | What is done with a picture pasted as pixels, a screenshot: the app keeps the pixels (image.to_png() into a file, a store of its own) and answers with the source the document names them by, and the editor puts that picture at the caret. Without it a paste of pixels does nothing: a document names its pictures and holds no pixels |
picture(Fn(&InlineObject) -> Element) | What is drawn for a picture of the document, in place of a Picture of its source: for pictures that are no files and no addresses (bytes the app holds, a resource, a key of its own store) |
controller(&RichTextController) | The app’s handle on the editor, kept from one render to the next: toggle_mark, set_paragraphs, toggle_paragraphs, set_link, insert_text, insert_link, insert_picture(source, label), insert_object(&InlineObject) for a picture with a width, select, undo, redo, value, and input(), the engine’s controller of its text |
invalid(bool), warning(bool), valid(bool) | What the app judged of what it holds: its edge in the destructive, warning or success color |
read_only(bool) | It is focused, selected and copied, and not changed: its tools take no input |
full_width(bool) | As wide as what holds it, in place of 560 |
label(&str) | What it is called, to what reads the tree |
name(..) | The name of its document in a form (feature form): its value there is the document as Markdown, as it is at each change |
toolbar_label, style_label, bold_label, italic_label, underline_label, strikethrough_label, bullet_label, ordered_label, quote_label, code_label, link_label, image_label, undo_label, redo_label, more_label, apply_label, remove_link_label | What each control is called |
paragraph_text, heading_text(Fn(level)), code_block_text, link_placeholder, shortcuts_text, count_text(Fn(words)) | The words it draws: the styles of its style control, the field of a link, and the footer’s two texts |
mount(ctx) | Puts it in the tree: it keeps the text being edited, what its bar shows and the panel of a link |
disabled(bool), state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. Its parts have the id with -content, -toolbar, -style, -bold and each tool’s name, -count and -link-field after it |
- Its value is a
RichText: the text, the marks over it (StyledSpans), what each paragraph is (ParagraphKind) and the pictures in it (InlineObjects).RichText::from_markdownandto_markdownread and write the Markdown an app stores. - A picture is a character of the document, alone in a paragraph or among words: an object of the engine’s input. It is as large as it is, or as wide as the document says (
InlineObject::width), and never wider than its line; its row is as high as it needs, and it stands on the baseline of the words beside it. The caret goes past it as past one character, a press selects it, Backspace after it selects it and the next deletes it, a selection takes it whole, and undo brings it back as it was. While the editor has the focus, a selected picture is under a veil of the selection’s color. It is no word to the count of the footer. Markdown writes it as an image,, or as<img src alt width>where it has a width, and a copy and a paste carry it so.insert_pictureisfalsein a line of a block of code, which holds no picture, and in an editor that takes no change. - A picture selected alone has a handle on its lower corner at the end: dragged, it makes the picture wider or narrower, from 16 to the width of the text, its height following its shape, as one step of the undo told to
on_changeonce, when it is let go. A read only or disabled editor has none. The width goes into the document (InlineObject::width) and into its Markdown as<img width>. - What is typed after a picture goes after it: a pasted or inserted picture has the caret after it, an arrow from a selected picture puts the caret before or after it, and Enter with a picture selected starts a paragraph after the picture and leaves it. Anything else typed over a selected picture takes its place, as over any selection.
- A paste of a clipboard with no words in it is a paste of pictures: pixels (a screenshot, an image copied in another app) go to
on_paste_image, and files that are pictures, copied in a file manager, are put in by their paths with no handler, each called by its file’s name. A clipboard that holds words is pasted as text, whatever else it holds. - A picture is drawn by a
Pictureof its source, an address where the source starts as one (http://,https://) and the path of a file otherwise, called by its label: it shows a skeleton while it loads and says so when it did not come. The pointer and the focus do not reach it, so it has no bar and opens no lightbox.picture(..)draws it another way. - It is the engine’s styled text input with kinds of paragraphs: the caret, the selection, the clipboard and the undo history are a text input’s own, and a selection runs over paragraphs of any kind. A copy keeps the formatting: the clipboard of the system is given the selection as Markdown where it has marks or a paragraph that is not body text (the plain text where it has neither), so another app or another lurq process pastes the Markdown, and an input of the same app the plain text while the clipboard still holds what was written. A paste of Markdown, or of a text that reads as it (a line with a block mark, or a mark Markdown reads), comes with its marks and kinds as one undo step; any other text, and anything pasted into a block of code, is plain text in the style at the caret.
- A tool works on the selection: a mark over the selected words, or over what is typed next where nothing is selected; a list, a quote or a style over every paragraph the selection touches, and a second press of a list or a quote makes them paragraphs again. The bar shows what the selection is: a mark’s tool is on while all of the selection has it, the style control says what its paragraphs are. A press of a tool leaves the focus in the text.
- The style control makes a paragraph body text, a heading of a level from 1 to 3, or a line of a block of code. The link tool opens a panel at the selection with a field for the target: Enter or Apply links the selection, an empty target or Remove link takes the link away, Escape changes nothing, and the focus goes back to the text.
- The keys, with Ctrl (Cmd on a Mac): B, I and U for bold, italic and underline, Shift+X to strike, E for code, K for a link, Alt+0 to Alt+3 for a paragraph and the headings, Shift+7, Shift+8 and Shift+9 for a numbered list, a bulleted one and a quote; undo and redo are the text input’s own, by lurq’s keys (Ctrl+Z, Ctrl+Shift+Z and Ctrl+Y, Cmd+Shift+Z on a Mac, in any layout) and an Edit menu’s, and the tooltips of Undo and Redo say those keys (
EditCommand::accelerator). Enter in an empty item or quote ends the list, Enter at the end of a heading starts a paragraph, and Backspace at the start of anything but a paragraph makes it one. - Markdown shortcuts:
#,##,###,-,*,1.,>and three backticks at the start of a paragraph make it what they say and are taken away;**bold**,*italic*,_italic_,`code`and~~struck~~become the mark as their last character is typed. - Parts:
RichTextEditorPart::Root,Toolbar(laid over a toolbar’s root),Tool,ToolOnandToolIcon(over its buttons and toggles, and a toggle that is on),Style,StyleChevronandStyleList(over a select’s trigger, chevron and panel),Content(the box: its padding, the type of body text, and its gap, the room between two paragraphs),Placeholder,Heading1,Heading2,Heading3(levels 4 to 6 are drawn as the third),BulletandBulletMark,OrderedandOrderedMark,QuoteandQuoteMark,CodeBlock,Footer,FooterText,LinkPanel(over a popover’s panel). A paragraph’s part gives its type over the content’s, its start padding is the room before its text, and a mark’s part its width, its gap to the text and its color. States:RichTextEditorState::Focused,Invalid,Warning,Valid,ReadOnly,Disabled,FullWidth. - In the design the box is 560 wide in
Backgroundwith an edge of 1 inBorderand the large radius. The bar is 40 high onMutedover a line of 1, padded 6, its tools 28 square with the small radius and icons of 15, 2 apart, one that is on filled withBackground(the board’saccentis the bar’s own fill, and would not show); the style control is 28 high and as wide as the name it shows (padded 10 before it and 6 after its chevron of 12, 6 from the name), its text 12, and its list as wide as its longest style with the check beside it. The box is padded 18 across and 16 down, its text the body’s 14 in rows of 18, its paragraphs 10 apart. A heading of the second level is 22 semibold in rows of 26 (the first 28 bold in rows of 34, the third 18 semibold in rows of 22). An item’s text starts 21 in after a dot of 5 inMutedForeground; a numbered item’s 24 in, 6 after its number; a quote’s 14 in, inMutedForeground, after a bar of 3 inBorder; a block of code is the mono family at 13 in rows of 21 onMuted, 12 in. A row is as high as its kind says, whatever the font’s own line is. The footer is 28 high over a line of 1, padded 12, its texts the mono family at 11 inMutedForeground; the count is of the runs of what is not white space. An empty editor draws its placeholder in the kind of its first paragraph, after its mark. - The board draws no picture in a document, only the tool: how one stands in its row, the veil of a selected one and its size are lurq’s, and it has no handles, no caption and no bar of its own.
- In a room narrower than its bar the tools that do not fit go into the menu of a More button at the bar’s end, as a toolbar’s do; the style control stays.
- To what reads the tree it is a
groupcalled by its label, with atoolbarof named tools and atextboxthat isa11y_multiline, in which each picture is animgcalled by its label. - Built without
mount(converted into an element) it is the still form of itself: the document as it is drawn, with nothing kept between two renders. A field the app mounts (Field::new("Notes", editor).mount(ctx)) mounts it, calls it by its label, judges it and disables it. - A renderer that draws another editor has
view.bar()(the toolbar, to add to),view.toolbar(it built),view.content(),view.footer(),view.link_panel(),view.root(),view.paragraph_styles()andview.format, what the selection is.
Editable
Section titled “Editable”A text that is read where it stands and edited in place: a title, a name, a cell.
use lurq::ui::Editable;
// title: Signal<String>, set when an edit is kept.Editable::new(title.clone()) .label("Project name") .placeholder("Untitled") .on_change(|name| println!("renamed to {name}")) .mount(ctx);
// A list of names: no buttons, as wide as the row.Editable::new(file.clone()).actions(false).full_width(true).mount(ctx);
// Held by the app, which starts the edit itself.Editable::controlled(&name, move |typed| rename(typed)).editing(renaming.clone()).mount(ctx);| Builder | |
|---|---|
new(Signal<String>) | The text. An edit that is kept is written into the signal |
controlled(value, on_change) | A text the app holds: an edit that is kept is told to on_change, and the text shown is what the app answers with |
on_change(handler) | Called with the new &str when an edit that changed it is kept: by Enter, the button, or leaving the field. The signal is set first. Not for an edit that changed nothing |
on_cancel(handler) | Called when an edit is dropped: by Escape or the button |
editing(Signal<bool>) | Whether it is being edited, in the app’s signal: the app starts an edit by setting it. Without it a mounted editable keeps this itself |
default_editing(bool) | Whether one that keeps this itself is being edited as it is first shown: a name just made |
on_editing_change(handler) | Called with true when a person starts an edit and with false when one ends, after on_change or on_cancel. Not when the app sets the signal |
placeholder(&str) | What the reading form shows while the text is empty, and the field while nothing is typed |
actions(bool) | Whether the editing form has the buttons that keep the edit and drop it: it has unless told |
submit_on_blur(bool) | Whether leaving the field keeps what was typed: it does unless told, and then leaving drops it |
invalid(bool) | What is typed is wrong: the field’s edge says so |
read_only(bool) | The text is read and cannot be edited: no pencil, and a press does nothing |
full_width(bool) | As wide as what holds it: the text is cut where it is longer, and the field fills the room its buttons leave |
label(&str) | What the text is, to what reads the tree |
confirm_label(&str), cancel_label(&str) | What its two buttons are called: “Save” and “Cancel” |
mount(ctx) | Puts it in the tree: it keeps whether it is being edited and what is typed, and moves the focus as an edit starts and ends |
disabled(bool), state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. The field has the id with -field after it, the buttons -confirm and -cancel |
- The reading form is one stop of Tab. A press of it, Enter, Space or F2 puts a field where the text was, with the text selected and the focus in it. Enter keeps what was typed and Escape drops it, as the two buttons do; leaving the field keeps it.
- When an edit ends by a key or a button the focus goes back to the reading form. When it ends because the focus went elsewhere, the focus stays where it went: Tab in the field keeps the edit and goes on to the control after the editable. The two buttons are pressed by the pointer and are no stops of Tab.
- Parts:
EditablePart::Root(the reading form),Label,Placeholder,Icon(the pencil),Editing(the row of the field and its buttons),Field(laid over an input’s root and control),ConfirmandCancel(over a button’s root). States:EditableState::Editing,Empty,Invalid,ReadOnly,Disabled,FullWidth. - In the design the reading form is a row 32 high: the text 16 semibold in
Foreground, and 8 after it a pencil of 14 inMutedForeground. Edited, a field 160 wide and 32 high with text of 14, and 6 after it two buttons 32 square with icons of 16: the outline one keeps the edit, the ghost one drops it. A text longer than its room is cut with an ellipsis, and the pencil keeps its place. - To what reads the tree the reading form is a button called by its label, with the text as its description; the field is a
textboxof the same name. - Built without
mountit is the still form of itself: the reading form, or the editing one where the app’s signal says so. - A renderer that draws another editable has
view.reading()andview.editor().
A message in the flow of a page about what is on it: a file that could not be saved, a disk that is nearly full, a shortcut to know.
use lurq::ui::{Alert, AlertVariant, Button, ButtonSize, ButtonVariant, Progress, icons};
Alert::new("Could not save") .description("The settings file is read-only.") .variant(AlertVariant::Destructive) .action(Button::new("Retry").variant(ButtonVariant::Outline).size(ButtonSize::Sm)) .on_close(move || shown.set(false));
// More than text under the description, and an icon of its own.Alert::new("Downloading lurq 0.61") .variant(AlertVariant::Info) .icon(icons::DOWNLOAD) .child(Progress::new(0.6).label("Downloading"));
// Several actions, under its words: the least first, the main one last.Alert::new("Working offline") .description("Changes are kept on this computer until the server answers again.") .variant(AlertVariant::Warning) .stacked(true) .action(Button::new("Details").variant(ButtonVariant::Ghost).size(ButtonSize::Sm)) .action(Button::new("Reconnect").variant(ButtonVariant::Outline).size(ButtonSize::Sm));| Builder | |
|---|---|
Alert::new(&str) | The title: what it is about. It is what the alert is called |
description(&str) | More of it, under the title |
variant(impl Into<Name>) | An AlertVariant: Neutral (the default), Info, Success, Warning, Destructive; a variant a theme adds has the neutral one’s icon and role |
icon(impl Into<IconChoice>) | An icon of the theme’s set in place of the variant’s (icon(icons::DOWNLOAD)), or none (icon(None)) |
action(element), actions(..) | Add what can be done about it, after those there: a button, a link. An alert has several, the least first and the main one last, at its end before the close control |
stacked(bool) | Its actions under its words, at their start and 8 under them, wrapping where one line does not hold them, and not at its end: for long words, or more actions than its end has room for |
actions_end(bool) | Actions under its words (stacked or compact) stand at their far end and not at their start. State actions_end |
align_top(bool) | The icon, the words, the actions at its end and the close control stand at the top, the actions on its first line, however many lines the words take; it is centred on the actions unless told. State align_top |
note(&str) | A quieter line after the actions, under the words: what a press of them does not say. Part Note (12, 1.5 high, MutedForeground), state note |
compact(bool) | Laid out for a narrow column, as an inspector has it: the icon beside the title alone (part Head, 8 apart, with the close control at its end), and the description, the body, the actions and the note under them across the whole box, 6 under the head. Its actions are under its words. State compact |
Alert::untitled() | An alert with no title: its description says it all. An empty title draws no title part, and the alert is called by its description |
child(element), children(..) | Elements under the description, for more than text |
on_close(handler) | Called on a press of the close control, which an alert has once it is given on_close and has not until then. The app takes the alert away. A second handler is called after the first |
label(&str) | What it is called to tooling, in place of its title |
role(&str) | What it is to tooling, in place of the variant’s |
state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. force draws the close control’s states; id is the id of the box |
- It is read where it stands and is not an overlay. It is as wide as the room it is given, and its title and description wrap in the room the icon, the actions and the close control leave them; a stacked alert’s words have all of its width but the icon’s and the close control’s.
- Its actions are 8 apart in the part
Action, at its end and centred on their height, or in a stacked alert under the description and the body, as wide as the words. Given an idx, the row of them isx-action; each action keeps the id the app gave it. - The close control is a stop of Tab with the focus ring; Enter, Space and a click press it.
- To what reads the tree (
lurq_snapshotof the MCP server) a warning and a destructive alert are analert, which a screen reader says at once, and the others astatus, said when the reader is done; each is called by its title, or by itslabel.role("status")says a warning is no news,role("alert")that an informative one is urgent.AlertVariant::role()is the variant’s. - Parts:
AlertPart::Root(the box),Icon,Text(the title, the description, the body, a stacked alert’s actions and the note, one over the other),Title,Description,Body,Action,Close,Note,Head(a compact alert’s icon and title). States:AlertState::Action, which centres what is in the box on the actions where they are at its end,Stacked, its actions under its words,AlignTop,Note,CompactandActionsEnd. Variants byAlertVariant. - Given an id
x, its parts arex-icon,x-text,x-title,x-description,x-body,x-action(the row of the actions),x-note,x-headandx-close. An app whose own notice named the words under the titlex-bodyand its actionsx-actionsreadsx-descriptionandx-action: the names of the parts, which a theme’s rules style. - In the design the box is in the
Cardcolor with an edge of 1 inBorder, corners ofradius-lg, padded 16. The icon is 16, 12 from the title (14, medium,Foreground) over the description (13, 1.5 high,MutedForeground), 4 apart. An informative, a successful and a warning alert are inInfoMuted,SuccessMuted,WarningMuted, with an edge and an icon ofInfo,Success,Warningand a description inForeground. A destructive one keeps theCardcolor, with an edge, an icon and a title ofDestructive. The icon is the information sign for a neutral and an informative alert, the check in a circle for a successful one, the warning sign for a warning and a destructive one. The close control is 16 inMutedForeground, inForegroundunder the pointer. AlertVariantis shared with the banner and the callout:icon(),accent()(the color of its icon, edge, bar and link) andtint()(its fill) say the same for the three.- The icon is the information sign for a neutral alert as for an informative one, as the board draws it.
- A renderer that draws another alert starts from
view.text()(with a stacked or compact alert’s actions under the words, and the note),view.icon(),view.title()(Nonefor an untitled one),view.actions(),view.note(),view.head()(a compact alert’s) andview.close()(the behavior), withview.role,view.label,view.name(),view.close_button,view.stacked,view.align_top,view.compactandview.actions_end.view.variantis the variant’s name, andview.actionswhat the app gave it to do.
Banner
Section titled “Banner”A message across the full width of what holds it, one line where it fits, at the top of a window or a page: a new version, a connection lost, a trial that ends. The app shows it and takes it away.
use lurq::ui::{AlertVariant, Banner, BannerPart, Link, icons};
Banner::new("lurq 0.61 is available with faster text shaping.") .variant(AlertVariant::Info) .link(Link::new("Update now").on_click(|_| update())) .open(open.get()) .on_close(move || open.set(false));
// Along the top edge of a window: in its middle, with no corners of its own.Banner::new("No connection. Changes will sync later.") .variant(AlertVariant::Warning) .icon(icons::WIFI_OFF) .centered(true) .style(BannerPart::Panel, |s| s.radius(0.0));| Builder | |
|---|---|
Banner::new(&str) | What it says. It is what the banner is called |
variant(impl Into<Name>) | As an alert’s. A neutral and an informative banner have the megaphone |
icon(impl Into<IconChoice>) | An icon of its own, or none: icon(None) |
link(Link) | A link after the text, in the variant’s color and semibold |
action(element) | Any element after the text in place of a link: a button. A banner has one action: a second, or a link, takes its place |
on_close(handler) | Called on a press of the close control, which a banner has once it is given on_close and has not until then. A second handler is called after the first |
open(bool) | Whether it is shown: the app’s to say, which a press of the close control does not change. It is unless it says |
label(&str) | What it is called to tooling, in place of its text |
centered(bool) | Its icon, text and action in its middle rather than from its start |
sticky(bool) | It sticks to the top of what scrolls the page it is on |
role(&str), state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As an alert has them. id is the id of the bar, key the key of what stands in the page |
- It stays in the tree whether it is shown or not, so it fades in as
open(true)shows it and out asopen(false)takes it away (thePanelpart’senterandexit:ui::FADE_INover the theme’s base duration,ui::FADE_OUTover its fast one). Taken away it is no height, and what is under it moves up. - A text too long for one line goes on to the next in the room the rest leaves it; a centred one is as wide as it is, and no wider than that room.
sticky(true)gives what stands in the page the engine’sSticky::top(0.0): in a scroll container it stays at the top while the page scrolls under it.- The link and the close control are stops of Tab, in that order. To what reads the tree it is an
alertor astatusas an alert is, called by its label or its text. - Parts:
BannerPart::Root(what stands in the page, sticky or not),Panel(the bar),Icon,Label(what it says),Action,Link(the style a link given bylinktakes over the theme’s for a link),Close. States:BannerState::Centered,Sticky. - In the design the bar is in the muted form of the variant’s color (
Mutedfor a neutral one), with corners ofradius-md, padded 10 and 16, what is in it 12 apart and centred on a line: the icon of 16 in the variant’s color, the text of 13 inForeground, the link 13 and semibold in the variant’s color, the close control 16 inForeground. - A renderer that draws another banner starts from
view.panel(), or fromview.icon(),view.text(),view.action()andview.close().
Callout
Section titled “Callout”A note set apart inside prose or a form: a hint beside a setting, a caution in a page of documentation.
use lurq::ui::{AlertVariant, Callout, Link, icons};
Callout::new("Theme changes rerender only the components that read the theme.").variant(AlertVariant::Info);
// The note of a document: a bar along its start, the icon before its title.Callout::new("Use backdrop blur for panels over busy content.") .title("Tip") .variant(AlertVariant::Success) .icon(icons::LIGHTBULB) .bar(true);
// In a form, with what the app puts under its text.Callout::new("The key is shown once.") .title("Before you go on") .variant(AlertVariant::Warning) .child(Link::new("How keys are stored").external());| Builder | |
|---|---|
Callout::new(&str) | What it says. An empty text says nothing, for a callout of a title and elements |
title(&str) | What it is, in a word, over its text. It is what the callout is called |
child(element), children(..) | Elements under the text |
variant(impl Into<Name>), icon(impl Into<IconChoice>) | As an alert has them |
bar(bool) | A bar along its start in the variant’s color, and the icon before a title in that color |
label(&str) | What it is called to tooling, in place of its title |
role(&str), state(name, on), style(part, ..), rules(&recipe), id, key | As an alert has them |
- Its words are given to
newand its title is the word over them, where an alert and a toast have a title and adescriptionunder it: a callout’s one sentence is what it says, and “Tip” or “Note” is what it is. - It is read, and is no stop of Tab. To what reads the tree it is a
note, called by its label, or by its title where it has one. - Without a bar, the icon stands at its start and the title, the text and the elements beside it. With a bar and a title, the icon and the title are a header over the text; with a bar and no title, the icon stands at the start as without one.
- Parts:
CalloutPart::Root(the box),Icon,Header(the icon and the title, with a bar),Text(the title, what it says and the elements),Title,Label(what it says). States:CalloutState::Bar,Title. - In the design the box is in the muted form of the variant’s color (
Mutedfor a neutral one), with corners ofradius-md, padded 12 and 14; the icon of 16 in the variant’s color is 10 from the text, 13 inForegroundand 1.5 high; a title is 13 and semibold. With a bar (the board’s Markdown/Admonition) the bar is 3 wide in the variant’s color and the corners on its side are square; the icon is 8 before a title of 14, semibold, in the variant’s color, and the text of 14 is 4 under them.
A key of the keyboard, the keys of a shortcut pressed together, or steps pressed one after another: what a person presses to do something.
use lurq::ui::{InlineCode, Kbd, KbdSize, KbdVariant, KeyPlatform};
Kbd::new("Esc");
// A key each. `Mod` is Ctrl, and ⌘ on a Mac.Kbd::shortcut("Mod+K").platform(KeyPlatform::current());
// Pressed one after another: G, then D; or two shortcuts.Kbd::sequence(["G", "D"]);Kbd::sequence(["Ctrl+K", "Ctrl+S"]).size(KbdSize::Lg);
// As a menu writes it: one text, no box. "⌘K" on a Mac.Kbd::shortcut("Mod+K").variant(KbdVariant::Plain);
// A short text of code in a run of text.InlineCode::new("ctx.theme()");| Builder | |
|---|---|
Kbd::new(&str) | One key, written as it is given: “Ctrl”, “Page Up”, ”/“ |
Kbd::shortcut(&str) | The keys of a shortcut, parted by +, a box each. A + after another, or alone, is the key of that name: Ctrl++ |
Kbd::sequence(steps) | Steps pressed one after another, each a key or a shortcut, with “then” between them |
Kbd::accelerator(&Accelerator) | The keys of an accelerator of the app’s menu: its modifiers, then its key |
platform(KeyPlatform) | Standard (words, the default) or Mac (⌃ ⌥ ⇧ ⌘, ↩ ⌫ ⇥ ⌦, the modifiers first in a Mac’s order). KeyPlatform::current() is the platform the app is built for |
variant(KbdVariant) | Default (a box for each key) or Plain (each step as one text in the muted color, with no box: “Ctrl+K”, “⌘K”) |
size(KbdSize) | Sm 16 high at 10, Md 20 at 11, Lg 24 at 12 |
separator_text(&str) | The word between the steps of a sequence: “then” unless told |
label(&str) | What the keys are called to what reads the tree, in place of their words |
state(name, on), style(part, ..), rules(&recipe), id, key | As a badge has them. id is the id of the root |
- Keys are named as lurq names them in a
KeyboardEvent(Escape,ArrowUp,Backspace,PageUp) or as a person writes them, in any case and with spaces or none:Esc,Del,Page Up.Modis Ctrl, and ⌘ on a Mac;Meta,Cmd,SuperandWinare ⌘ on a Mac. Arrows are drawn as ↑ ↓ ← →. A single letter is drawn in capitals; a key lurq does not name is drawn as it is written (UpstaysUp). - On a Mac the modifiers are glyphs and stand first, in the order
Accelerator::displaywrites them: ⌃ ⌥ ⇧ ⌘. In words they keep the order they are given in. - Keys are read and not operated: they take no press, no focus and no stop of Tab. To what reads the tree (
lurq_snapshotof the MCP server) they are onetext, called by their label or their keys in words: “Ctrl+K”, “Cmd+Shift+P”, “G then D”. - Parts:
KbdPart::Root(the row of keys, its gap),Key(a key’s box),Label(the text on a key, or of a plain step),Separator(what stands between steps). Variants:KbdVariant. Sizes:KbdSize. States:KbdState::Sequence,Mac. - In the design a key is 20 high, padded 6, on
Mutedwith an edge of 1 inBorderand the radiusSm, its text 11 in the family of code inMutedForeground. The keys of a shortcut are 4 apart with nothing between them; large ones are 24 high, padded 7, at 12 and 6 apart, as the list of an app’s shortcuts has them. Plain is the text of a menu’s shortcut: 11 in the family of code inMutedForeground. - A renderer that draws other keys has
view.steps(each step’s keys, with what is drawn on each and what it is called),view.root(),view.key_cap(key),view.label(text),view.between()andview.written(step)(a step as one text). InlineCode::new(&str)is a short text of code in a run of text: 13 in the family of code inForeground, onMutedwith the radiusSm, padded 5 across and 1 above and below. It is not cut, and iscodeto what reads the tree, called by its text. Parts:InlineCodePart::Root,Label.
Code Block
Section titled “Code Block”A block of code: a snippet in a page of docs, a command to run, a file’s lines. Its words are in the colors of what they are, under a bar with its name and a button that copies it.
use lurq::ui::CodeBlock;
CodeBlock::new("fn main() {\n let app = App::new();\n}") .language("rust") .title("main.rs") .line_numbers(true) .highlight_lines([2]) .on_copy(|code| println!("copied {} bytes", code.len())) .mount(ctx);| Builder | |
|---|---|
CodeBlock::new(&str) | The code. A newline at its end is not a line of its own |
language(&str) | Whose tokenizer tells its words apart (see Highlighting code: lurq’s own for Rust, TOML, JSON, JavaScript, TypeScript, shells, Python, CSS, HTML, XML, YAML, SQL and Markdown, or the app’s), what the bar shows where it has no title, and what tooling is told. A language with no tokenizer is drawn in one color |
tokenizer(impl Into<CodeTokenizer>) | A tokenizer of the block’s own in place of its language’s: any Fn(&str) -> Vec<CodeToken>, a Tokenizer, or a CodeLanguage table. Made once and cloned into each render, what it gave is kept |
token_style(name, |s| ..) | Styles the tokens of a name ("keyword", "string.escape") over the theme’s code colors: color, weight, leaning. A part of that name in the block’s recipe, so a theme’s rules style it too |
code_scheme(CodeScheme) | The block’s own colors of code in place of the theme’s: a block that looks apart, as a terminal’s |
title(&str), label(&str) | What the bar shows in place of the language, a file’s name, on one line ending in an ellipsis; its name to what reads the tree, its title or its language unless told |
line_numbers(bool), first_line(usize) | The numbers of the lines, in a column at their start that a selection does not take; the number of the first, 1 unless told |
highlight_lines(lines) | Lines picked out by their numbers: a band in Highlight behind each, across the block, its number in the code’s color |
wrap(bool) | Wraps the lines at the block’s width. Otherwise each is one line, and the code scrolls sideways under the scroll area’s bar |
min_height(..), max_height(..) | The least and the greatest height, its bar with it: past the greatest, the code scrolls down and the bar stays |
copy_button(bool), copy_label(&str), copied_text(&str), on_copy(Fn(&str)) | The button in the bar that copies the code (shown unless told otherwise), its name (“Copy code”) and its name while it shows it copied (“Copied”); on_copy is told the code it put on the clipboard |
copy_text(&str) | What the button copies in place of the code shown: a command shown short and copied whole. on_copy is told it |
copy_failed_text(&str) | The button’s name while it shows that the clipboard refused the copy (“Couldn’t copy”, the locale’s EditingWords::copy_failed) |
selectable(bool) | Whether a person selects the code: on unless told otherwise. Selectable, the code is a read-only input, a stop of Tab: the arrows move a caret through it, Shift with them selects, Ctrl+A takes it all, Ctrl+C copies, and the pointer selects across its lines. Off, it is text that what holds it makes selectable with its own (a Markdown document) |
framed(bool) | Whether it is drawn in a frame of its own, as it is unless told otherwise: off, its bar and its code stand on what holds them (a card that frames them) |
header(bool) | Whether it has its bar: where it has a title, a language or a copy button unless told. Told not to, the language still colors the code |
row_height(f32) | How high each line is: 21 (CODE_BLOCK_ROW_HEIGHT) unless told, the code’s own line of 17 and 4 between; the padding of 14 around the lines is kept to the glyphs of the first and the last |
mount(ctx) | Mounted where it is declared, the copy button shows a check in Success, named copied_text, for two seconds (CODE_BLOCK_COPIED_FOR) after the clipboard took the code, or an alert in Destructive, named copy_failed_text (state CopyFailed), where it refused it, and a long block follows its scrolling. Converted into an element on its own it copies and does not show that it did; a long block of a greatest height is mounted as mount mounts it |
state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. force draws the copy button under the pointer or held; id is the block’s, with {id}-title, {id}-copy and {id}-code |
- The bar is there where the block has a title, a language or a copy button; with none of them the code stands alone in the block.
- The code is one text in both forms, scrolling sideways and wrapped, and a selection runs across its lines and copies them with their line breaks. Its numbers stand in the input’s gutter at the first row of each line as it is laid out (
components::LineGutter), and a picked line’s band covers every row it wrapped into; neither is selected or copied. The copy button copies all of it. - A press of the copy button puts the code on the clipboard through the window it is in (
WindowHandle::copy_to_clipboard): the OS clipboard with theclipboardfeature, the clipboard the app gives in its place (App::set_clipboard_writer, so that a QA copy or a gallery never writes the person’s), or what a test installs. It says it copied, or could not, by what that clipboard answers. Thenon_copyis told. - Its words are told apart by the tokenizer registered for its language (
lurq::code, which Markdown’s code blocks,InlineCodeand a code field use too, without themarkdownfeature), or by its own. Each token has a dotted name (keyword.control,string.escape,function.macro), and is drawn in the style the block’s recipe gives a part of that name, or the theme’s code colors give it (Theme::set_code_color,CodeScheme), dropping the tail of a name neither has:keyword.control.rust, thenkeyword.control, thenkeyword, then the code’s own color. The theme’s colors unless told (CodeScheme::lurq) are the palette’s roles: keywords inInfo, as the board drawsfnandlet, and where the board is silent types, namespaces, tags, keys,selfand the language’s constants (true) inInfo, strings inSuccess, numbers, constants and attributes inWarning, comments, operators and punctuation inMutedForeground; functions and variables in the code’s own. - A block of more than 400 lines (
CODE_BLOCK_WINDOWED_LINES) lays out and paints the lines in view and a chunk of 64 lines on each side, and is as high as all of them: ten thousand lines draw what a screen of them draws. In view is in its own room where it has a greatest height, and in the window where it has none (a long fence of a Markdown document): it follows its room’s scroll and the page’s around it, and takes the lines in view before the frame is painted. It does so mounted, or as.child(block);build(theme)draws a block with no greatest height whole, and one with a greatest height from its first line. Its tokens are kept by the tokenizer and the code, so a render that changes nothing of its code does not tokenize it again. In that form a person selects the lines drawn with the pointer, its scroll area is the stop of Tab, and select all (Ctrl+A) takes the code whole, onSelection, which a copy (Ctrl+C) then copies whole, all ten thousand lines; a press in the code lets it go. Its copy button copies all of it. A wrapped one counts each line’s rows by its characters at its width, the figures of the family of code being as wide as each other, from its first frame. - The code scrolls in a scroll area. Selectable, the code is the stop of Tab; otherwise the area is, called by the block’s name, and its keys scroll it.
- To what reads the tree it is
code, called by its label, its title or its language, witha11y_language, and so is its code (a11y_readonly); its copy button is abuttoncalled bycopy_label, orcopied_textwhile it shows it copied. - Parts:
CodeBlockPart::Root,Header,Title,Copy,CopyIcon,Body,Code,LineNumber,Marked(the band of a line picked out), and a part for each name of a token, by its name ("keyword","string.escape"): its foreground, weight and leaning are its tokens’, over the theme’s code colors. States:CodeBlockState::Header,LineNumbers,Wrap,Copied,CopyFailed,Framed. - In the design the block is on
Backgroundin an edge of 1 inBorderwith the large radius. Its bar is 36 high onMutedwith a line of 1 inBorderunder it, padded 14 at its start and 6 at its end; its title is 11 in the family of code inMutedForeground, and its copy button a ghost button of 28 with a copy glyph of 16 inForeground,Highlightunder the pointer. The code is 13 in the family of code inForeground, padded 14, its lines 17 high and 4 apart. Where the board is silent: the numbers are inMutedForeground16 before the code, a picked line’s band isHighlight, and a long line scrolls sideways. - A renderer that draws another block has
view.header(),view.copy_control(),view.body(),view.root(),view.spans(code)(code in runs of its tokens’ styles),view.tokens(the code’s, by its tokenizer),view.lines(),view.name()andview.heading(), andview.render()the default.
Blockquote
Section titled “Blockquote”A quote set apart from the text around it by a line at its start: words someone said, a passage of another text, Markdown’s >.
use lurq::{app::theme::TypographyStyle, components::Text, ui::Blockquote};
Blockquote::new("A design system is a set of decisions you no longer have to make.");
// Paragraphs, as Markdown's `>` holds them.Blockquote::new("") .child(Text::new("First paragraph.").variant(TypographyStyle::Prose)) .child(Text::new("Second paragraph.").variant(TypographyStyle::Prose));| Builder | |
|---|---|
Blockquote::new(&str) | What it says, wrapping at its width. An empty text says nothing, for a quote of elements alone |
child(..), children(..) | Elements under the text, 8 apart: paragraphs, a list, a block of code. What names no color of its own takes the quote’s |
label(&str) | What it is called to tooling: who said it, where it is from |
state(name, on), style(part, ..), rules(&recipe), id, key | As a badge has them |
- It fills the width it is given. It is read and not operated: no stop of Tab. To what reads the tree it is a
blockquote, called by its label where it has one. - Parts:
BlockquotePart::Root(the line, the padding),Label(the text),Body(what it holds under its text). States:BlockquoteState::Body. - In the design it has a line of 2 in
Borderat its start, and is padded 16 after it and 4 above and below; its text is 14 in italics on lines of 1.5 inMutedForeground. The board draws no one who said it. - A renderer that draws another quote has
view.root(),view.label(),view.body()andview.render().
Bulleted List
Section titled “Bulleted List”A list of lines, each with a mark before it: a bullet, a number, an icon or a mark of the app’s own. The features of a plan, the steps of a recipe, what a release changed; Markdown’s - and 1. are drawn with the same numbers.
use lurq::ui::{BulletedList, BulletedListItem, BulletedListMarker, icons};
BulletedList::new(["Semantic color roles", "Light and dark palettes"]);
// Numbers, from 4, written as the app says.BulletedList::new(["Install", "Configure", "Run"]) .marker(BulletedListMarker::Number) .start(4) .number_text(|number| format!("{number})"));
// An icon for every item: the name of one is a marker.BulletedList::new(["Signed", "Notarized"]).marker(icons::CHECK);
// A list in an item, with a marker of its own.BulletedList::new(["Tokens"]).item( BulletedListItem::new("Components") .list(BulletedList::new(["Button", "Switch"]).marker(BulletedListMarker::Number)),);| Builder | |
|---|---|
BulletedList::new(items) | Its items: texts, or BulletedListItems |
item(..), items(..) | Adds to them |
marker(impl Into<BulletedListMarker>) | What stands before each item: Bullet (the default), Number, Icon(name), or None, the lines alone. The name of an icon of the theme’s set is a marker |
start(u64) | The number of the first item of a numbered list, in place of 1 |
number_text(Fn(u64) -> String) | How a numbered list writes a number, in place of 1.: a), a number in another script |
label(&str) | What it is called to tooling |
state(name, on), style(part, ..), rules(&recipe), id, key | As a badge has them. What is said of a list is said of the lists in its items |
| Item | |
|---|---|
BulletedListItem::new(&str) | What it says, wrapping at the list’s width. An empty text says nothing, for an item of elements alone |
child(..), children(..) | Elements under its line, 6 apart: a paragraph, a block of code |
list(BulletedList) | A list in the item, under what it says and holds: set in to the item’s text, its bullets rings, with the marker it was given |
icon(name) | An icon as this item’s mark, in place of the list’s |
media(..) | An element of the app’s as this item’s mark: a status dot, a picture |
id, key | Of the item’s row |
- It fills the width it is given. A mark stands in the middle of its item’s first line, however many lines the item goes on to. It is read and not operated: no stop of Tab. To what reads the tree it is a
listoflistitems, called by its label where it has one. - An icon or a mark of one item’s own makes an icon’s room before every item of that list, so that their lines start together; an item of it with neither keeps its bullet.
- Parts:
BulletedListPart::Root(the room between the items),Item(a mark and a body, and the room between them),Mark(the box a mark stands in, one line high: its width, and the type and color of a number),Bullet,Label(what an item says),Body(the line over what the item holds). States:BulletedListState::Numbered,Icon,Nested(it is in another list’s item). - In the design (
btfDc) its items are 6 apart, each a dot of 5 inMutedForeground, 10 before its text in the body’s 14 inForeground. Where the board is silent it has the Markdown document’s lists: a number at the end of a width of 18 inMutedForeground, 8 before the text, a ring for the bullet of a list in an item, an icon of 14. The numbers of a Markdown document’s lists (ThemeMarkdown::list_item_spacing,bullet_size,bullet_gap,list_marker_gap,ordered_list_marker_width) start from the same source, so the two are one look until a theme changes one. - A renderer that draws another list has
view.root(),view.item(index, item),view.mark(index, icon, media),view.label(text),view.number(index),view.line_height()andview.render().
Empty State
Section titled “Empty State”What stands where content would be when there is none, and what to do about it: no results, no windows yet, all caught up.
use lurq::ui::{Button, ButtonSize, ButtonVariant, EmptyState, EmptyStateSize, Length, icons};
EmptyState::new("No windows yet") .description("Open a window to see it listed here.") .icon(icons::INBOX) .action(Button::new("New window").icon(icons::PLUS).variant(ButtonVariant::Outline));
// In a table or a list: the icon alone, no edge; centred in all of the room the list would have.EmptyState::new("No crates match") .description("Check the spelling or clear the filter.") .icon(icons::SEARCH_CLOSE) .size(EmptyStateSize::Sm) .height(Length::Fill) .action(Button::new("Clear filter").variant(ButtonVariant::Outline).size(ButtonSize::Sm));| Builder | |
|---|---|
EmptyState::new(&str) | What is empty, in a line. It is what the empty state is called |
label(&str) | What it is called to what reads the tree, in place of its title |
description(&str) | Why, or what to do, under the title |
icon(name) | An icon of the theme’s set over the title, in its well |
media(element) | An element of the app’s in place of the icon and its well: an illustration, a picture |
action(element), actions(elements) | Add something to do under the text, after what is there: an empty state has one or two, the main one last |
size(EmptyStateSize) | Sm (the icon alone, 22, everything 10 apart), Md (a well of 40, in an edge), Lg (a round well of 64, a title of 18) |
bordered(bool) | An edge around it. Md has one unless told; Sm and Lg have none |
width(Length) | A width of its own in place of all of the room it is given |
height(Length) | A height of its own, in which what it holds is centred: Length::Fill for all of the room a parent that stretches it gives |
state(name, on), style(part, ..), rules(&recipe), id, key | As a badge has them. id is the id of the root |
- It is as wide as the room it is given and as high as what is in it, all of it centred; the title and the description wrap in the width there is. Its actions are the app’s elements, as large as the place has them: a small button in a table.
- It is read; what it gives to do is operated as itself. To what reads the tree it is a
status, called by its label or its title, with its description asa11y_description. - Parts:
EmptyStatePart::Root,Mark(the well),Icon,Text(the title over the description),Title,Description,Actions. Sizes:EmptyStateSize. States:EmptyStateState::Bordered. - In the design the medium one is padded 32, with 16 between the well, the text and the actions, in an edge of 1 in
Borderwith the radiusXl; the well is 40 onMutedwith the radiusLg, its icon 20 inForeground; the title is 14/500 inForeground, the description 4 under it at 13 inMutedForeground; the actions are 8 apart. The small one is the empty table’s: padded 32 and 16, everything 10 apart, the icon 22 inMutedForegroundwith no well. The large one is the phone’s: padded 32 and 24, a round well of 64 with an icon of 28, a title of 18/600 and a description of 15, 6 apart. - A renderer that draws another empty state has
view.root(),view.mark()(the app’s element or the icon in its well),view.text()andview.actions().
Result
Section titled “Result”What a page or a dialog says when something is over: payment received, build failed, nothing here. It is ui::Outcome in the code, so that use lurq::ui::* does not hide std::result::Result.
use lurq::ui::{Button, ButtonVariant, Outcome, OutcomeVariant};
Outcome::new("Build succeeded") .description("412 tests passed in 38 seconds.") .action(Button::new("View log").variant(ButtonVariant::Outline)) .action(Button::new("Deploy"));
// On a page of its own, or in a dialog: no box.Outcome::new("Nothing here") .variant(OutcomeVariant::NotFound) .description("This page was moved or never existed.") .bordered(false) .action(Button::new("Home"));| Builder | |
|---|---|
Outcome::new(&str) | Its title, what came of it in a line, which is what it is called |
variant(OutcomeVariant) | What came of it: Info, Success (unless told), Warning, Destructive or NotFound (a 404), or a variant the theme’s recipe names, marked with the information sign |
label(&str) | What it is called to what reads the tree, in place of its title |
description(&str) | More of it, under the title |
icon(impl Into<IconChoice>) | Another icon of the theme’s set in the mark, in the variant’s colors; None for no mark |
media(element) | An element of the app’s in place of the mark |
child(element), children(elements) | Add what stands under the text and over the buttons, as wide as the outcome, 8 apart: a summary, a list |
action(element), actions(elements) | Add a button at the bottom, after those there: an outcome has several, the least first, the main one last |
bordered(bool) | A box of its own with a fill and an edge, as the design draws it: true unless told |
width(Length), height(Length) | A width of its own in place of the design’s 300; a height of its own, what it holds centred in it |
state(name, on), style(part, ..), rules(&recipe), id, key | As a badge has them. id is the id of the root |
- Everything in it is centred; its title and description wrap in its width. With no box it has no padding either, and stands where what holds it puts it: a column that centres it on a page, the body of a dialog.
- It is read; its buttons are operated as themselves. To what reads the tree it is a
status, called by its label or its title, with its description asa11y_description. - Parts:
OutcomePart::Root,Mark,Icon,Text,Title,Description,Body(what the app put under the text),Actions. Variants:OutcomeVariant(OutcomeVariant::icon()is the icon each is marked with). States:OutcomeState::Bordered. - In the design it is 300 wide, padded 24 with 16 between the mark, the text and the buttons, on
Backgroundin an edge of 1 inBorderwith the radiusLg. The mark is a circle of 48 in the variant’s muted color, its icon 24 in the variant’s color: a check inSuccess, a cross inDestructive, a warning inWarning, aniinInfo, and a crossed magnifier inForegroundonMutedfor not found. The title is 16/600 inForeground, the description 4 under it at 13 inMutedForeground; the buttons are 8 apart. - A renderer that draws another outcome has
view.root(),view.mark()(Nonewith no icon and no media),view.text(),view.body()andview.actions().
Message Box
Section titled “Message Box”A dialog that asks one question or says one thing and waits for the answer: replace a file, save the changes, delete projects.
use lurq::ui::{MessageBox, MessageBoxRole, MessageBoxVariant, icons};
MessageBox::new(open.clone()) .variant(MessageBoxVariant::Warning) .title("Replace existing file?") .description("“theme.json” already exists in this folder. Replacing it overwrites its contents.") .checkbox("Don't ask again", again.clone()) .answer("Cancel", MessageBoxRole::Cancel, || {}) .answer("Replace", MessageBoxRole::Default, move || replace_file());
// A question whose confirming answer cannot be undone: the focus goes to Cancel.MessageBox::new(open.clone()) .icon(icons::TRASH) .title("Delete 3 projects?") .description("This cannot be undone.") .answer("Cancel", MessageBoxRole::Cancel, || {}) .answer("Delete", MessageBoxRole::Destructive, move || delete_projects());| Builder | |
|---|---|
MessageBox::new(Signal<bool>) | Shown while the signal holds true. The message box does not keep it: every answer sets it to false before what the answer does runs |
variant(MessageBoxVariant) | Info (the default, info), Question (help-circle), Warning (warning), Destructive (alert-circle): the icon in the mark and their colors. A theme may add variants by name |
icon(impl Into<IconChoice>) | An icon of the theme’s set in place of the variant’s: trash for a question that deletes. None for no icon, and no mark |
title(&str), description(&str) | What it asks or says, and more of it in the muted color. The title is what it is called, the description what describes it |
label(&str) | What it is called to tooling, over its title |
detail(&str, Signal<bool>) | A text behind “Details” under the description, open while the signal holds true; detail_label(&str) names the trigger |
checkbox(&str, Signal<bool>) | A checkbox at the start of the footer: “Don’t ask again” |
answer(&str, MessageBoxRole, handler) | An answer. Default: filled, Enter gives it. Cancel: outlined, Escape and a press of the veil give it. Destructive: in the destructive fill. Plain: outlined, at the start of the footer |
dismiss_on_escape(bool), dismiss_on_veil(bool) | Whether Escape, and a press of the veil, give the cancel answer. Both on by default; with no cancel answer neither closes it |
width(impl Into<Length>) | A width of its own over the board’s 400 |
inline(bool) | The panel where it is declared, without the veil: for a gallery, a screenshot, a test |
state(name, on), style(part, ..), rules(&recipe), id, key | As a dialog has them. id is the id of the panel |
- It is a dialog: the veil, the focus going in as it opens and back as it closes, and Tab going round its controls are the dialog’s. As it opens the focus goes to the confirming answer (the default one, or else a destructive one) unless that answer is destructive, and then to the cancel one, the least destructive answer: Enter or Space does not confirm what cannot be undone. A popconfirm asks by the same rule.
- Enter gives the default answer wherever the focus is, on the checkbox too, unless it is on another button, which Enter presses. Escape and a press of the veil give the cancel answer where there is one and do nothing where there is none.
- The plain answers stand at the start of the footer, after the checkbox, in their order; at its end the cancel answer stands first and the others after it, whatever order they were given in.
- Parts:
MessageBoxPart::VeilandPanel(laid over the dialog’s),Content,Header(the mark beside the text),Mark,Icon,Text,Title,Description,DetailTrigger,DetailChevron,DetailLabel,DetailPanel,Detail,Footer,Option,CheckboxandCheckboxLabel(laid over the checkbox’s root and label),Actions, and for each role a part laid over the button’s root and one over its label:DefaultButton,DefaultLabel,CancelButton,CancelLabel,DestructiveButton,DestructiveLabel,PlainButton,PlainLabel. Variants:MessageBoxVariant. States:MessageBoxState::Destructive(an answer is destructive: the icon in the destructive colors),DetailOpen. - So a theme gives the two buttons of a message box fonts or fills of their own without touching a button anywhere else:
theme.patch_recipe::<MessageBox>(|rules| rules.base(MessageBoxPart::DefaultLabel, |s| s.font_family("Georgia")).base(MessageBoxPart::CancelLabel, |s| s.font_family(FontFamily::Mono))). - In the design the panel is 400 wide, padded 20 with 16 between the header and the footer; the mark is 36 and round, in the variant’s muted color (
InfoMuted,Secondaryfor a question,WarningMuted,DestructiveMuted), its icon 18 in the variant’s color; the title is 15/600, 14 after the mark, over the description of 13 inMutedForeground, 4 apart; the buttons are 32 high, padded 14, 8 apart; the checkbox’s label is 13. “Details” is a chevron of 14 in the muted color 4 before its label of 13, and the detail opens 8 under it, in the mono type of 11 on theMutedfill, with its height over the theme’s base duration. - To what reads the tree it is an
alertdialogcalled by its label or its title and described by its description. - A renderer that draws another message box (an iOS alert: the text in the middle, the answers as cells side by side) has the pieces:
view.content()(with Enter),view.header(),view.mark(),view.title(),view.description(),view.find(role),view.press(index)(it closes the box and runs the answer),view.button(index)(the default renderer’s button, which takes the focus first where it should), andview.dialog(content), which puts what it built in the dialog with Escape, the veil and what tooling is told.
Popconfirm
Section titled “Popconfirm”A question in a small panel hung from what was pressed, answered by one of two buttons: delete a file, leave a channel.
use lurq::ui::{Button, ButtonVariant, Popconfirm};
Popconfirm::new(open.clone(), anchor.clone()) .trigger(Button::new("Delete file").variant(ButtonVariant::Outline)) .title("Delete this file?") .description("It will be moved to the trash.") .destructive(true) .confirm("Delete", move || delete_file()) .cancel("Keep", || {});| Builder | |
|---|---|
Popconfirm::new(Signal<bool>, anchor) | Shown while the signal holds true, hung from anchor. Keep the anchor from one render to the next, as for a popover |
trigger(element) | A button that asks: it is the anchor, and a press of it turns the signal |
title(&str), description(&str) | The question, and more of it in the muted color |
icon(impl Into<IconChoice>) | An icon of the theme’s set before the title, in place of the warning sign, or None for no icon |
confirm(&str, handler), cancel(&str, handler) | The two buttons: their labels (“Yes” and “No” when not given) and what each runs after it closes the popconfirm. Escape and a press outside run the cancel one |
destructive(bool) | The confirm button and the icon in the destructive color, and the focus on the cancel button as it opens |
placement(Placement), offset(impl Into<SpacingValue>), collision(CollisionStrategy) | Where it is beside its anchor and how far from it, as a popover has them: under it at its start, 4 from it, by default |
width(..) | How wide the panel is, over the recipe’s 250 |
label(&str) | What tooling calls it: its title by default |
on_dismiss(Fn()) | Runs after a person closed it by Escape or a press outside, after what the cancel button runs; not on a press of either button, nor when the app sets the signal. Each handler given runs, in order |
dismiss_on_escape(bool), dismiss_on_outside_press(bool) | Whether Escape, and a press outside it and its anchor, close it and cancel: both true by default |
inline(bool) | Draws the panel where it is declared, open or not, without its trigger: for a gallery, a screenshot, a test. Its buttons still answer |
state(name, on), style(part, ..), rules(&recipe), id, key | As a popover has them. id is the id of the panel |
- The title and the description wrap. Buttons too long to stand side by side go one under the other, the confirm button under the cancel one, both at the end. A button’s label wider than the panel is cut with an ellipsis inside it.
- It is a popover: kept in the window, gone to the other side where there is no room, the focus back on the anchor as it closes. As it opens the focus goes to the confirm button; where it is destructive, to the cancel button, the least destructive answer, so that Enter or Space does not remove what was not read. A message box puts the focus by the same rule.
- Escape and a press outside close it and run what the cancel button runs, then what
on_dismisswas given. A button closes it before its handler runs. - Parts:
PopconfirmPart::PanelandBody(laid over the popover’s panel and body),Content,Header(the row of the icon and the text),Icon,Text,Title,Description,Footer(the row of the buttons),CancelButton,CancelLabel,ConfirmButton,ConfirmLabel. States:PopconfirmState::Destructive. - In the design the panel is 250 wide, padded 12 with 12 between the header and the buttons, in the popover’s colors, edge, large radius and medium shadow; the icon is the warning sign of 16 in
Warning, 8 before the title of 13/500 over the description of 12 inMutedForeground, 2 apart; the buttons are 28 high, padded 10, their labels 13, 8 apart at the end. - To what reads the tree it is an
alertdialogcalled by its label or its title and described by its description. - A theme’s renderer builds what the panel holds from
PopconfirmView(header(),cancel(),confirm(),footer(),content()with Escape,confirmer(),canceller(),dismisser()); where the panel is shown, and when, stays the popover’s.
Progress Dialog
Section titled “Progress Dialog”A dialog over the window while a piece of work runs: what is being done, how far it is, and a way to stop it.
use lurq::ui::{ProgressDialog, icons};
ProgressDialog::new(open.clone()) .icon(icons::COPY) .title("Copying 128 items") .description("from Downloads to projects/lurq/assets") .value(copied.get()) .max(128.0) .format(|done, all| format!("{done} of {all}")) .status("about 2 min left") .detail(¤t_file.get(), details.clone()) .button("Pause", move || pause()) .on_cancel(move || stop());| Builder | |
|---|---|
ProgressDialog::new(Signal<bool>) | Shown while the signal holds true. It closes when the app sets it to false: Escape and a press of the veil do not close it |
icon(&str), title(&str), description(&str) | What kind of work it is, what is being done (what it is called), and a line more of it in the muted color |
label(&str) | What it is called to tooling, over its title |
value(f64), max(f64) | How far the work is, a fraction of one unless max says otherwise. Without a value its end is not known, and the bar runs a segment across it |
format(Fn(f32, f32) -> String) | Says how much is done under the start of the bar: “42 of 128”. A percentage when not given |
status(&str) | What the app says of the rest, under the end of the bar |
detail(&str, Signal<bool>) | A text behind “Details” at the start of the footer, open under the footer while the signal holds true; detail_label(&str) names the trigger |
button(&str, handler) | Adds a button before the cancel one: “Pause”. It does not close the dialog |
on_cancel(handler), cancel_label(&str) | A cancel button, which has the focus as the dialog opens and which Escape presses. It does not close the dialog: the app does once the work has stopped. A second handler runs after the first |
width(impl Into<Length>), inline(bool), state(name, on), style(part, ..), rules(&recipe), id, key | As a message box has them |
- The title and the description wrap. The count is never cut; a status longer than what the count leaves is cut with an ellipsis on one line.
- It is a dialog with its veil, its focus and its Tab, which nothing but the app closes.
- Parts:
ProgressDialogPart::VeilandPanel(laid over the dialog’s),Content,Header,Icon,Text,Title,Description,Progress(laid over the progress’s root),Meta,Count,Status,Footer,DetailTrigger,DetailChevron,DetailLabel,DetailPanel,Detail,Actions,ActionButton,ActionLabel,CancelButton,CancelLabel. States:ProgressDialogState::Indeterminate,DetailOpen. - In the design the panel is 420 wide, padded 20 with 12 between its parts; the icon is 20, 12 before the title of 15/600 over the description of 12 in
MutedForeground, 2 apart; the bar is the progress’s of 6 across the panel; what is done and what is left are in the mono type of 11 inMutedForeground; the footer, 4 further down, has “Details” at its start and the outlined buttons of 32, padded 14, 8 apart, at its end. - To what reads the tree it is a
dialogcalled by its label or its title and described by its description, with theprogressbarin it.
A panel that slides in from an edge of the window, over the page, for what goes with the page without leaving it: edit a profile, filter a list, share a document.
use lurq::{ components::SheetDetent, ui::{Button, ButtonVariant, Input, Sheet, SheetSide, SheetSize},};
// open: Signal<bool>, the app's.let close = open.clone();Sheet::new(open.clone()) .title("Edit profile") .description("Changes save when you close the panel.") .close_button(true) .child(Input::new(name.clone())) .footer(Button::new("Close").variant(ButtonVariant::Outline).on_click(move |_| close.set(false))) .footer(Button::new("Save"));
// From the start, wider.Sheet::new(filters_open.clone()).side(SheetSide::Start).size(SheetSize::Md).title("Filters").children(filters);
// At the bottom, mounted: a finger drags it between its heights and down to put it away.Sheet::new(goal_open.clone()) .side(SheetSide::Bottom) .title("Move goal") .detents([SheetDetent::Content, SheetDetent::Large]) .footer(Button::new("Submit")) .mount(ctx);| Builder | |
|---|---|
new(Signal<bool>) | Shown while the signal holds true. The sheet does not keep it: Escape, a press on the veil and the close button set it to false |
side(SheetSide) | The edge it comes from: End (the default) and Start as high as the window, Top and Bottom as wide as it |
size(SheetSize) | Across from its edge: Sm 320, Md 400, Lg 540 wide at a side, Sm 240, Md 360, Lg 480 high at the top or the bottom, Full the window. Without one it is 320 wide at a side and as high as what it holds at the top or the bottom. Never larger than the window |
title(&str), description(&str) | What it is, and more of it under the title. The title is what the sheet is called |
label(&str) | What the sheet is called to tooling where it has no title |
child(element), children(..) | The body, which scrolls between the header and the footer |
footer(element) | Adds to the footer, the least action first and the main one last: a row at the panel’s end under a line, or at the bottom a column of buttons as wide as the sheet with the main one on top |
close_button(bool), close_label(&str) | A ghost button with the close icon at the end of the header, and what it is called to tooling: “Close” when not given |
grabber(bool) | The handle at the top. A sheet at the bottom has it unless told otherwise |
dismiss_on_veil(bool), dismiss_on_escape(bool) | Whether a press on the veil (and, mounted, a drag down), and Escape, close it. Both on by default |
on_dismiss(Fn()) | Runs after a person closed it: a press on the veil, the close button, Escape wherever the focus is (the engine’s Modal::on_dismiss), and for a mounted sheet at the bottom a finger that drags it down and away or taps beside it (SheetProps::on_dismiss). A button of the app’s that closes it, or the app setting the signal, does not run it. A second handler runs after the first |
detents([SheetDetent]), detent(Signal<usize>), scroll_state(ScrollState) | For a mounted sheet at the bottom: the heights it stands at, which it is at, and the body’s scrolling, which hands a finger to the sheet once the body is at its top |
body_scrolls(bool) | Whether the body scrolls. It does unless told; one that does not is laid out in the room the panel has for it, at a side the panel’s height less the header and the footer, for what holds a scroll of its own. A drawer over the page with body_scrolls(false) gives its sheet this |
inline(bool) | The panel where it is declared, without the veil and without taking the window: for a gallery, a screenshot, a test |
mount(ctx) | At the bottom, the engine’s draggable Sheet in this look; at another edge, the same as converting it |
state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. force draws the close button as under the pointer, pressed or focused; id is the panel’s; key tells two sheets of one component apart |
- A title or a description longer than the panel wraps inside its padding on every side, centered where the sheet stands at the bottom and the top; neither is cut. A drawer over the page is a sheet, and wraps the same.
- It is the engine’s
Modalwithtarget(Root)andtakes_focus(true), as a dialog is: declared anywhere, it takes no room there and covers the window under the window’s own title bar while it is open. As it opens the focus goes to its first control (the close button where it has one), and as it closes back to what had it. Nothing under the veil takes the pointer, and Tab and Shift+Tab go round the sheet’s own controls. A press on the panel goes no further. - It slides in from its edge over the theme’s slow duration in the entering curve as the veil fades in, and out to it over the base duration in the leaving curve: keyframes that move the panel by its own width or height (
ui::SHEET_IN_FROM_START..ui::SHEET_OUT_TO_BOTTOM). With motion reduced (Theme::reduced_motion, stateModalwithReducedMotion) it fades where it stands. - At the start and the end the body takes the room the header and the footer leave, so the footer stands at the panel’s bottom; at the top and the bottom the sheet is as high as what it holds while that fits, and the body gives way and scrolls when it does not.
mount(ctx)puts a sheet at the bottom on the engine’s sheet: a finger drags it between itsdetents(or the height its size gives it, or its content’s) and throws it down to close it, it rises over the on-screen keyboard and keeps clear of a phone’s edges, and it comes up with a spring. The engine lays out the panel and the backdrop; the recipe’sPanelandVeildress them (SheetProps::dress), and what the panel holds is the sheet’s. A theme’s renderer builds the sheet that is converted, not the mounted one, which is made of the view’s parts.- Parts:
SheetPart::Veil,Panel,Grabber(the strip at the top of a bottom sheet),Handle(its bar),Header(the text and the close button),Text(the title over the description),Title,Description,Body,Footer,Close(a button restyled),Separator(the separator over the footer, restyled). Variants:SheetSide. Sizes:SheetSize. States:SheetState::Modal(over the window, not inline),ReducedMotion. - In the design a sheet at a side is in
Backgroundwith a line of 1 inBorderalong the edge it shows the page and the large shadow. The header is padded 20 at the top and the sides, the title 16/600 inForegroundover the description in 13MutedForeground, 4 apart, the close button’s icon of 16 inMutedForegroundat its end; the body is padded 20 with 16 between what it holds; the footer is padded 16 and 20, its buttons 8 apart at the end, under a line ofBorder. At the top the line is along its bottom. At the bottom it is the board’s drawer: a line all round, corners ofradius-xl(12) at its top, a handle of 40 by 4 inMuted8 under its top edge, the text in the middle 20 under it, and its buttons as wide as it, 8 apart, 20 from the edges. The veil isScrim. - The board’s phone and tablet sheets are the same parts restyled: the phone’s bottom sheet a panel of 360 round 20 at its top with a handle of 36 in
Input, its title 18 and its description 14, padded 16; the tablet’s form sheet a panel of 520 by 360 round 16 with an edge all round. The gallery’s page has them. - To what reads the tree (
lurq_snapshotof the MCP server) the panel is adialogcalled by its title, or by its label. - A renderer that draws another sheet has
view.panel(),view.grabber(),view.text(),view.close(),view.header(),view.body(),view.footer(),view.separator(),view.contents()(all of them in order),view.veil(panel)andview.modal(panel).
Drawer
Section titled “Drawer”A panel at one side of a layout, beside the page rather than over it, that opens and closes: the navigation of an app, a pane of details or of filters.
use lurq::{ components::Row, ui::{Drawer, SheetSide},};
// open: Signal<bool>, the app's. The drawer pushes the page aside.Row::new() .child(Drawer::new(open.clone()).label("Navigation").children(places)) .child(page);
// On a narrow window it lies over the page with a veil.Drawer::new(open.clone()).label("Navigation").overlay(narrow).children(places);| Builder | |
|---|---|
new(Signal<bool>) | Open while the signal holds true. The app’s: over the page, Escape and a press on the veil set it to false |
side(SheetSide) | The side of the layout it stands at: Start (the default) and End open with its width, Top and Bottom with the height of what it holds |
label(&str) | What it is called to tooling |
child(element), children(..) | What it holds, which scrolls where it is too small |
width(impl Into<Length>), height(impl Into<Length>) | A width of its own at a side (300 without one), a height of its own at the top or the bottom |
overlay(bool) | Over the page with a veil, as a sheet at its edge, rather than beside it: for a window too narrow to push the page aside |
body_scrolls(bool) | Whether what it holds scrolls where it is too small. It does unless told; what does not is laid out at the panel’s height, beside the page and over it, for what holds a scroll of its own with something that stays beside it: a sidebar with its header and its footer |
dismiss_on_veil(bool), dismiss_on_escape(bool) | Over the page, whether a press on the veil, and Escape, close it. Both on by default |
on_dismiss(Fn()) | Over the page, runs after a person closed it by the veil or Escape, as a sheet’s does. A second handler runs after the first |
inline(bool) | Over the page, its panel where it is declared, without the veil and without taking the window: for a gallery, a screenshot, a test. A drawer beside the page is where it is declared already |
state(name, on), style(part, ..), rules(&recipe), id, key | As a button has them. id is the panel’s |
- It is declared in the layout where it stands, at the start or the end of a row or the top or the bottom of a column. As it opens its room grows from nothing to the panel’s over the theme’s slow duration and pushes the page aside, and the panel, which keeps its size, comes out from the layout’s edge and fades in; as it closes the room closes over it as it fades out, and what it held is gone, so that Tab does not reach it. With motion reduced it opens and closes at once.
overlay(true)builds a sheet at the drawer’s edge, as large across as the drawer’s panel, holding what the drawer holds laid out as in the drawer: it takes no room in the layout, slides in over a veil, and is a dialog to tooling.- Parts:
DrawerPart::Root(the room it takes, with the transition of its width or height),Panel,Body. Variants:SheetSide. States:DrawerState::Open. - In the design (the board’s navigation drawer) the panel is 300 wide in
Backgroundwith a line of 1 inBorderalong the edge it shows the page; what it holds pads itself. - To what reads the tree it is a
complementaryregion called by its label. - A renderer that draws another drawer has
view.body(),view.panel()andview.root(panel), andview.is_open.
Hover Card
Section titled “Hover Card”More about what the pointer rests on, a person, a link, a file, in a panel beside it. Unlike a tooltip it holds what a person reads and presses.
use lurq::{ components::Placement, ui::{Avatar, Button, ButtonSize, HoverCard, Link, icons},};
// In a component's render: a hover card is mounted on the element it is about, and returns that element.let author = HoverCard::new() .media(Avatar::new("LQ")) .title("@lurq") .description("A Rust UI toolkit with GPU-backed rendering.") .fact("Joined March 2024", icons::CALENDAR_DAYS) .mount(ctx, Link::new("@lurq"));
// With controls in it: a dialog to tooling, and Tab goes into it from the link.let reviewer = HoverCard::new() .title("Ivan Zaida") .child(Button::new("Follow").size(ButtonSize::Sm)) .placement(Placement::Right) .arrow(true) .mount(ctx, Link::new("Ivan Zaida"));| Builder | |
|---|---|
mount(ctx, element) | Puts the card on the element it is about and returns that element |
title(&str), description(&str) | What it is about, and a line or two about it |
label(&str) | What tooling calls it, in place of its title |
media(element) | What stands at its start, beside the text: an avatar, the icon of a file |
fact(&str, icon), facts(..) | A fact in the row under the description: its text, and an icon of the theme’s set before it or None |
child(element), children(..) | What it holds under its text: a link, a row of buttons |
placement(Placement) | The side of the element it is on and the edge it lines up with: Bottom, centered, by default |
offset(..), collision(CollisionStrategy) | How far it stands from the element in place of the theme’s 8, and what it does where there is no room on its side: FlipThenClamp by default |
arrow(bool) | A triangle with the panel’s edge from the panel to the element |
open_delay(..), close_delay(..) | A MotionDuration of the theme’s or a Duration: how long the pointer rests before it opens (Slower, 400 ms) and how long it stays after the pointer left (Slow, 240 ms) |
force_open(Option<bool>) | Some(true) shows it whatever the pointer and the focus do, Some(false) never |
disabled(bool) | It never opens, and the element is as it would be without it |
pass_through(bool) | The pointer passes through the card to what is under it, and the card goes as the pointer leaves the element, with no close delay: a card of words over a status bar’s item. Off by default |
width(..), state(name, on), style(part, ..), rules(&recipe), id, key | As a popover has them. id is the id of what shows |
- It opens when the pointer has rested on the element for its open delay, and at once when the keyboard’s focus comes to the element or to anything in it. It stays open while the pointer is on the element, on the card or crossing the room between them (the room is the card’s root, which the pointer is on), and while the focus is in either; it closes when the pointer has left both for its close delay, when the focus leaves both, and on Escape, which it takes before anything under it. After Escape it stays closed until the pointer comes again or both the pointer and the focus have left.
- A card that the pointer passes through (
pass_through(true)) is hit by nothing: what it covers is hovered and pressed through it, and it goes the moment the pointer leaves the element. The focus and Escape show and put it away as they do any card. - Tab goes from the element into the card’s controls and on to what follows the element (
Overlay::tab_after_anchor): the focus is not moved into it as it opens, which is whatOverlay::takes_focuswould do. As it closes with the focus inside, the focus goes back to the element. - One hover card of the pointer shows at a time. Where there is no room on its side it goes to the other, its arrow turned with it, and where the window pushes it along, its arrow still points at the middle of the element.
- To what reads the tree it is a
dialogwhere it holds a control and atooltipwhere it does not, called by its label or else its title; the element is described by the title and the description (a11y_description), and says it has a dialog where the card has controls. - It is a mounted component, as the tooltip is. Converted into an element on its own, a
HoverCardis its panel as it shows, anchored to nothing. As a tooltip, it has noon_dismissand nodismiss_on_escape: the pointer and the focus open it, not the app, and Escape always closes it. - Parts:
HoverCardPart::Root(the panel and its arrow, and the room between them and the element),Panel,Media,Text,Title,Description,Facts,Fact,FactIcon,Arrow. States:HoverCardState::Arrow,Controls, and the side it is on by the names ofTooltipSide("top","bottom","left","right"). - In the design the panel is 300 wide on
Popoverin an edge of 1 inBorder,Lground, with theMdshadow and 16 of padding, the media 12 before the text. The text is 6 apart: the title in 14 at medium weight, the description in 13 ofMutedForegroundin lines of 1.5, and the facts 12 apart, each an icon of 14 6 before its text in 12, both muted. It stands 8 from the element; the arrow is 18 along the panel and 9 out from it. It fades in over the base duration and out over the fast one.
Toggletip
Section titled “Toggletip”A tooltip opened by a press: a small button beside a label that opens a few words about it, for what must be reachable by a finger and told by a screen reader.
use lurq::ui::Toggletip;
let help = Toggletip::new("What is a workspace?") .text("A workspace holds the projects a team shares.") .link("Learn more", || open_docs()) .mount(ctx);| Builder | |
|---|---|
Toggletip::new(&str) | What its button is called to tooling: the question the panel answers |
mount(ctx) | Puts its button where it goes, and its panel over the window while it is open |
text(&str) | What the panel says |
link(&str, Fn()) | A link under the text, with an arrow after it, and what a press of it does |
child(element), children(..) | What the panel holds under its text: a button |
icon(name) | The button’s icon, icons::INFO unless this says otherwise |
placement(Placement) | The side of the button the panel is on and the edge it lines up with: Top, centered, by default |
offset(..), collision(CollisionStrategy) | How far the panel stands from the button in place of the theme’s 6, and what it does where there is no room on its side: FlipThenClamp by default |
arrow(bool) | A triangle from the panel to the button: the tooltip’s |
on_dismiss(Fn()) | Told after a person closed it: another press of its button, a press outside it, Escape. A second handler is called after the first |
dismiss_on_escape(bool), dismiss_on_outside_press(bool) | Whether Escape, and a press outside it and its button, close it: both on by default |
force_open(Option<bool>) | Some(true) shows the panel whatever the button says, Some(false) never |
disabled(bool) | The button takes nothing |
force(Option<Interaction>) | Draws its button hovered, pressed or focused with nothing on it |
width(..), state(name, on), style(part, ..), rules(&recipe), key | As a popover has them |
id | The id of the button; the root of the panel is <id>-panel |
- A press of the button opens the panel and another closes it; a press outside it and Escape close it too, and each of the three tells
on_dismissonce it is closed. The focus stays on the button as it opens, and Tab goes from the button into the panel’s link and on; as the panel closes with the focus in it, the focus goes back to the button. - To what reads the tree the button is called by its label and says whether it is expanded (
a11y_expanded), and the panel is astatus. - It is a mounted component: it keeps whether it is open. Converted into an element on its own, a
Toggletipis its panel as it shows. - Parts:
ToggletipPart::Root,TriggerandTriggerIcon(what it gives the theme’s button and its icon),Panel,Label(its text),LinkandLinkLabel(what it gives the theme’s link and its label),Arrow. States:ToggletipState::Open,Arrow,Disabled, and the side as a hover card has it. - In the design the panel is 230 wide on
Primary,Mdround, with 12 of padding and 8 between what it holds. Its text is 13 inPrimaryForegroundin lines of 1.4, and its link 13 at 600 with an arrow up and right of 14, underlined inPrimaryForegroundunder the pointer. The button is a ghost one of 20 that is a circle, its icon of 14 inMutedForeground, inForegroundunder the pointer and while the panel is open. The panel stands 6 from the button, and its arrow is the tooltip’s, 12 along and 6 out.
Teaching Tip
Section titled “Teaching Tip”A panel that points at one thing in the app and says what it is for, the first time a person comes to it or when it is new, without taking the focus from what they are doing. A tour shows several, one after another.
use lurq::ui::{Icon, TeachingTip, TeachingTipVariant, Tour, TourStep, icons};
// open: Signal<bool>, anchor: ElementRef, kept by the app.let close = open.clone();let dock = TeachingTip::new(open.clone(), anchor.clone()) .media(Icon::new(icons::SPARKLES).size(24.0)) .title("Dock panels anywhere") .description("Drag a panel by its header and drop it on any edge of the window.") .primary("Got it", move || close.set(false)) .mount(ctx);
// step: Signal<Option<usize>>, which step shows; None while the tour is not on.let tour = Tour::new(step.clone()) .step(TourStep::new(theme_button, "Switch themes here").description("Light and dark palettes share the same roles.")) .step(TourStep::new(panels, "Dock panels anywhere")) .mount(ctx);| Builder | |
|---|---|
TeachingTip::new(open, anchor) | Pointing at anchor while the Signal<bool> is true |
mount(ctx) | Puts it in the app; the element it returns has no size and goes anywhere |
title(&str), description(&str) | What it points at, and what it is for |
label(&str) | What tooling calls it, in place of its title |
media(element) | A picture or an icon at its top, on a muted fill as wide as it |
child(element), children(..) | What it holds under the description |
step(n, of) | That it is a step of several: “2 of 4” in its footer, in the tour’s look |
primary(&str, Fn()), secondary(&str, Fn()) | The button that goes on, and the one before it, and what a press of each does |
tertiary(&str, Fn()) | A quiet button before them, “Skip”, “Remind me later”, and what a press of it does |
on_dismiss(Fn()) | Told after its close control, Escape or a press outside it closed it: the signal is false already. A second handler is called after the first |
dismiss_on_escape(bool) | Whether Escape closes it, as its close control does: on by default |
dismiss_on_outside_press(bool) | Whether a press outside it closes it: off by default, since a press elsewhere is the person going on with what they do beside it |
close_button(bool) | A close control at the end of its title: on by default |
variant(TeachingTipVariant) | Plain (the default), in the popover’s colors, or Primary |
placement(Placement) | The side of what it points at it is on and the edge it lines up with: Bottom, centered, by default |
offset(..), collision(CollisionStrategy) | How far it stands from what it points at in place of the theme’s 4, and what it does where there is no room on its side: FlipThenClamp by default |
arrow(bool) | A triangle with the panel’s edge pointing at what it is about: on by default |
takes_focus(bool) | The focus goes into it as it opens and back as it closes. Off by default |
traps_tab(bool) | Tab stays in it while the focus is in it, going round from its last button to its first. Off by default; a tour turns it on |
force(Option<Interaction>) | Draws its close control hovered, pressed or focused with nothing on it |
width(..), state(name, on), style(part, ..), rules(&recipe), key | As a popover has them |
id | The id of what shows; its close control is <id>-close, its buttons <id>-primary, <id>-secondary and <id>-tertiary |
- It does not keep whether it is open: the app’s signal does. Its close control and Escape close it: they set the signal to
falseand then tellon_dismiss, so that a handler that opens something else does not have it closed under it. A press elsewhere does not close it, so a person can go on with what they are doing beside it. Its own buttons do what their handlers say. - It does not take the focus unless the app says so: Tab goes from what it points at into its buttons and on (
Overlay::tab_after_anchor). Withtakes_focus(true)the focus goes into it as it opens and back to what had it as it closes. - To what reads the tree it is a
dialogcalled by its label or else its title. Where there is no room on its side it goes to the other, its arrow turned with it, and the arrow points at the middle of what it is about. Tour::new(Signal<Option<usize>>)shows the step the signal says, counted from 0, as a teaching tip with its count and no close control, with “Back” from the second step on and “Next”, or “Done” on the last (back_label,next_label,done_label). Its buttons set the signal; Done and Escape set it toNone, and then Done tellson_finishand Escapeon_dismiss(dismiss_on_escape(false)keeps the tour on;dismiss_on_outside_press(true)leaves it on a press outside the tip, as Escape does).skip_button(true)gives every step but the last a quiet “Skip” before the others (skip_label), which leaves as Escape does; the design draws none, so it is off by default.TourStep::new(anchor, title)hasdescription,media,placement,idandkey; the tour hasvariant,placement,offset,collisionandarrowfor all its steps, andstate,style,rules,idandkeyfor the tip that shows, a step’sidandkeyfirst.Tour::controlled(Option<usize>, on_change)is given the step as a value the app holds: a press of its buttons, its keys and Escape tellon_changethe step it is asked to be at, and it stays where the app holds it. Bound,on_change(Fn(Option<usize>))is told the step after the signal is set,Noneas the tour ends or is left, beforeon_finishandon_dismiss; it is not told when the app sets the signal.- A tour takes the focus (
takes_focus(false)leaves it where it is, as a teaching tip does): into its card as it starts, on the button that goes on whatever stands before it, on the button that was pressed from step to step, on “Next” where “Back” is gone with the first step, and back to what had it before the tour as it ends. Tab is held in the card (traps_tab(false)lets it go on to what follows what the step points at): from its last button it goes round to its first, and Shift+Tab the other way; the page behind still answers the pointer. While the focus is in the card the Right arrow goes on a step and the Left one back, Home and End go to the first and the last step, and none of them ends the tour: Done and Escape do. The card of all its steps is one overlay that goes from one element to the next (see Popups And Outside Presses). - Teaching tips and tours are mounted components: a tip keeps which side the window let it take, and what Escape tells. Converted into an element on its own, a
TeachingTipis its panel as it shows, and aTourthe panel of the step its signal says, or of its first step while it says none. - Parts:
TeachingTipPart::Root,Panel,Media,Content(the text over the footer),Text,Header(the title and the close control),Title,Close(what it gives the theme’s button),Description,Footer,Step,Actions,PrimaryAction,SecondaryActionandTertiaryAction(what it gives the theme’s buttons),Arrow. Variants:TeachingTipVariant::Plain,Primary. States:TeachingTipState::Arrow,Step(it has a count),Media, and the side as a hover card has it. - In the design a teaching tip is 300 wide on
Popoverin an edge of 1 inBorder,Lground, with theLgshadow: media 96 high onMuted, then 14 of padding around the text and the footer 10 under it. The title is 14 at 600 with a ghost close control of 20 at its end, its icon of 16 inMutedForeground; the description 6 under it is 13 ofMutedForegroundin lines of 1.45; the buttons, 8 apart at the end of the footer, are 30 high and 12 from their sides, the primary onePrimaryand the otherOutline. It stands 4 from what it points at; its arrow is 18 along the panel and 9 out from it, with the panel’s edge. A step of a tour is the board’s Tour: 280 wide with theMdshadow, padded 16, its title at 500 over the description 4 under it in lines of 1.5, its footer 12 under them with the count in mono 11 ofMutedForegroundat its start and buttons 28 high and 10 from their sides. In thePrimarylook the panel isPrimaryin its own color’s edge, all it says inPrimaryForeground, the media on a white of 10%, and the buttonsSecondaryandGhost. It fades in and out as the popover does.
Notification
Section titled “Notification”Something that happened which a person may act on now or later: who or what it is from, a title and a line, when, what can be done about it, whether it was read. A card on its own, and a row of a list of them.
use lurq::ui::{Avatar, Notification, NotificationVariant};
// The design's card: the bell, a title over a line, a button, and what dismisses it.Notification::new("Review requested") .description("Ivy asked you to review feat/node-blur.") .button("Review", move || open_review()) .on_close(move || dismiss(id));
// A row of a list: who it is from, when, and that it was not read.Notification::new("Ivy Chen requested a review") .description("feat/node-blur") .media(Avatar::new("Ivy Chen")) .time("2m") .unread(true) .variant(NotificationVariant::Row) .on_click(move |_| open(id));| Builder | |
|---|---|
Notification::new(&str) | The title: what happened. It is what the notification is called |
description(&str) | More of it, under the title |
media(element) | Who or what it is from, before the text in place of the icon: an Avatar, an app’s mark |
icon(impl Into<IconChoice>) | An icon of the theme’s set in place of the bell, or none (icon(None)) |
time(&str) | When it happened, as the app words it: “2m” |
unread(bool) | Whether it was not read: it has the dot, and a row’s title is medium |
button(&str, Fn()) | Adds a button under the text: the first is the primary one, the others ghosts |
action(element) | Adds something of the app’s own to the actions: a link, a menu’s button. It adds, since a notification has several |
child(element), children(..) | Elements under the description, for more than text |
variant(impl Into<Name>) | A NotificationVariant: Card (the default), with an edge and a shadow, or Row, as a list draws each |
on_click(handler) | A press of the whole notification: it opens what it is about. A second handler is called after the first |
on_close(Fn()) | Called on a press of what dismisses it, which it has once it is given on_close: a “Dismiss” button after a card’s own, a close control at the end of a row. The app takes the notification out of what it lists |
close_label(&str), unread_label(&str) | What dismisses it says and is called (“Dismiss”), and what its dot is called to tooling (“Unread”) |
label(&str) | What it is called to tooling, in place of its title |
state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. force draws the notification’s states where it is pressed, and else those of a row’s close control; id is the id of the box, with <id>-close and <id>-action-0, <id>-action-1 for what is in it |
- A notification stays: it is there until the app takes it out of what it lists. A toast leaves by itself and is shown over the window from anywhere; an alert, a banner and a callout are part of the page they stand in and say something about it. It keeps nothing: whether it was read and whether it is listed are the app’s, and it tells what a person did.
- Given
on_clickit is pressed as a whole: a button to what reads the tree, a stop of Tab with the ring inside it, pressed by Enter and Space. Its own buttons and what dismisses it are pressed apart from it, each a stop of Tab after it. Withouton_clickit is anarticlethat takes no focus and answers no pointer. - A title and a description longer than their room wrap; the time stays whole on one line; buttons that do not fit side by side go on to the next line. A card is 340 wide at most and as wide as a narrower room.
- A row follows the theme’s density: 56 high at the default, 48 compact, 64 comfortable and 68 under a finger. A row that was read keeps the room of the dot, so what stands after it lines up down a list.
- Parts:
NotificationPart::Root,Unread(the dot),Media,Icon,Content(the text over the body and the actions),Text,Header(the title, and on a card the time and the dot),Title,Time,Description,Body,Actions,Action(what it gives the theme’s buttons),Close(a row’s close control). Variants:NotificationVariant::Card,Row. States:NotificationState::Unread,Pressable. - In the design the card is 340 wide on
Popoverin an edge of 1 inBorder,Lground, with theMdshadow, padded 16: the bell of 16 inForeground, 12 from the title (14, medium) over the description (13,MutedForeground, lines of 1.4) 4 under it, and 10 under them the buttons, 28 high, 10 from their sides and 8 apart. The row is 12 from its top, its bottom and its start and 16 from its end, with 10 between the dot of 7 inInfo, the avatar of 32, the text (the title 13 over the description of 12 inMutedForeground, 1 apart) and the time in mono 11 inMutedForeground; under the pointer it is inHighlight, as the board draws its first row. The board draws no time and no dot on a card: they stand after its title. It draws no pressed card and no focus: a pressed card has the veils of those states. - A renderer that draws another notification starts from
view.media(),view.text(),view.content(),view.actions(),view.close(),view.unread_dot(),view.time()andview.root(children)(the behavior), withview.row,view.unreadandview.close_button.
Notification Center
Section titled “Notification Center”The panel that lists an app’s notifications, opened from its bell: a header with what marks all read or clears, the notifications as rows, and a footer that leads to all of them.
use lurq::ui::{Avatar, Badge, Button, ButtonVariant, Notification, NotificationCenter, icons};
// open: Signal<bool> and bell: ElementRef, kept by the app; listed: Signal<Vec<(Id, bool)>>, its list.let unread = listed.get().iter().filter(|(_, read)| !read).count();NotificationCenter::new(open.clone(), bell.clone()) .trigger(Badge::count(unread).label("unread notifications").on( Button::new("Notifications").icon(icons::BELL).icon_only(true).variant(ButtonVariant::Ghost), )) .items(listed.get().into_iter().map(|(id, read)| row(id).unread(!read))) .on_mark_all_read(move || mark.update(|all| all.iter_mut().for_each(|(_, read)| *read = true))) .on_clear(move || clear.set(Vec::new())) .on_view_all(move || go_to_inbox());| Builder | |
|---|---|
NotificationCenter::new(open, anchor) | Shown beside anchor, the bell, while the Signal<bool> is true |
trigger(element) | What opens and closes it: a Button, or a Badge with its count or its dot on one. It is put before the panel and is its anchor; the first thing in it that takes the focus is what is pressed, and says whether the panel is open |
title(&str) | What the panel is called, at its top and to tooling: “Notifications” by default |
item(Notification), items(..) | What it lists. Each is drawn as a row, whatever its own variant |
on_mark_all_read(Fn()) | Draws “Mark all read” in the header and is called on a press of it. The control takes no press while nothing is unread |
on_clear(Fn()) | Draws “Clear all” in the header and is called on a press of it. The control takes no press while the list is empty |
on_view_all(Fn()) | Draws the footer, “View all”, and is called on a press of it, after the panel closed |
mark_all_read_label(&str), clear_label(&str), view_all_label(&str) | What each control says |
empty_text(&str), empty(element) | What it says under an inbox while it lists nothing (“No notifications”), or the app’s own empty state in their place |
on_dismiss(Fn()) | Told after a press outside it or Escape closed it; not when the app sets the signal, and not on “View all” |
dismiss_on_escape(bool), dismiss_on_outside_press(bool) | Whether each closes it: both by default |
placement(Placement), offset(..), collision(CollisionStrategy) | Under the bell with its end at the bell’s end (BottomEnd), the theme’s smallest spacing from it, and to the other side then into the window where there is no room |
width(..), max_height(..) | How wide the panel is (360), and how high the list is at most before it scrolls (360) |
inline(bool) | Draws the panel where it is declared, open or not, with no trigger: a panel of a page, a gallery, a test |
label(&str), state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a popover has them. force draws its first pressed row’s states; its controls are <id>-mark-all-read, <id>-clear and <id>-view-all |
- The list and what is read are the app’s. The panel tells what a person did (its three handlers, and each notification’s own
on_clickandon_close) and is given the list as it is then; it keeps nothing but what a popover keeps, and is built anew with each render. - As it opens the focus goes into it, to the first thing in it that takes the focus, and back to the bell as it closes. Tab stops in the rows once and the arrow keys move between those that are pressed; a row’s close control is a stop of Tab after it. “View all” closes the panel first and then tells, so what the handler opens keeps the focus it takes.
- The list is as high as its rows up to its greatest height and scrolls past it, under the header and over the footer, and gives way where the window has less room. A title longer than the header’s room is cut with an ellipsis; the controls keep their room.
- To what reads the tree it is a
dialogcalled by its label or its title, holding alistof the same name; its bell saysa11y_haspopupand whether it is expanded. - Parts:
NotificationCenterPart::Panel,Header,Title,Actions,ActionandActionLabel(what they give the theme’s link),List,Item(what holds a row that has another under it: the line between the two),Empty,EmptyIcon,EmptyText,Footer. States:NotificationCenterState::Footer,Empty. The rows are styled byNotification’s recipe. - In the design the panel is 360 wide on
Popoverin an edge of 1 inBorder,Xlround, with theLgshadow. The header is 48 high and 16 from its sides over a line inBorder: the title at 15, semibold, and “Mark all read” at 13, medium, inInfo. A row is 56 with a line inBorderalong its bottom, and the footer 40 with “View all” at 13, medium, in its middle. The board draws three rows and no end of the list, no empty panel and nothing under the pointer: the list scrolls past 360, an empty panel has an inbox of 24 over its words at 13, bothMutedForeground, 32 over and under them, the header’s controls are underlined under the pointer as a link is, and the footer is inHighlight. It fades in and out as the popover does.
AI Label
Section titled “AI Label”The mark on what a model made or filled in, and on what asks one: a summary that was generated, a field that was suggested.
use lurq::ui::{AiLabel, AiLabelSize};
AiLabel::new();// Said otherwise, and called by more than it draws.AiLabel::new().text("Draft").label("Drafted by the assistant");AiLabel::new().size(AiLabelSize::Sm).icon(None);| Builder | |
|---|---|
new() | Sparkles and “AI” |
text(&str) | The word it draws in place of “AI”: the app’s word for it, or the word in another language |
label(&str) | What it is called to tooling, where that is more than the word it draws: “Generated by AI” |
icon(IconChoice) | An icon of the theme’s set in place of the sparkles; None for no icon |
size(AiLabelSize) | Sm 18, Md 22 (the default, the board’s), Lg 26 |
state(name, on), style(part, ..), rules(&recipe), id, key | As a button has them |
- It is read and not operated: it takes no press, no focus and no stop of Tab. To what reads the tree it is a
notecalled by its label, or by its word. - What explains it stands on it as on any element:
Tooltip::new("…").mount(ctx, AiLabel::new()), or a toggletip beside it. - A word longer than the room it has ends in an ellipsis, and the icon keeps its place before it.
- Parts:
AiLabelPart::Root,Icon,Label. State:AiLabelState::Icon(it has one). Sizes:AiLabelSize. - In the design it is 22 high with the corners of
RadiusSize::Sm, onInfoMutedin an edge of 1 inInfo, padded 8, with sparkles of 12 4 before “AI” in 11 and semibold, both inInfo. The board draws that one size: small is 18, padded 6, at 10 with an icon of 10, and large 26, padded 10, at 12 with an icon of 14, the steps of a badge.
Back To Top
Section titled “Back To Top”A round button that shows once a page is scrolled down, and takes it back to its top.
use lurq::{ components::{Column, Stack}, layout::{StackAlignment, layout_kind::ScrollState}, ui::{BackToTop, ScrollArea},};
// scroll: ScrollState, kept by the page and given to what scrolls it too.Stack::new() .stack_align(StackAlignment::BottomEnd) .child(ScrollArea::new().scroll_state(scroll.clone()).children(article)) .child(Column::new().padding(16.0).overflow_visible().child(BackToTop::new(&scroll).mount(ctx)));| Builder | |
|---|---|
new(&ScrollState) | The state of what it scrolls |
threshold(f32) | How far down the content is scrolled before the button shows: 300 (ui::BACK_TO_TOP_THRESHOLD) unless told; at 0, as soon as it leaves its top |
label(&str) | What the button is called to tooling, in place of “Back to top” |
icon(name) | Its icon, in place of the arrow that points up |
on_click(..) | Hears the press, and Enter and Space, before the content is scrolled; a handler that prevents the event’s default keeps the content where it is. A second handler is called after the first |
force_shown(Option<bool>) | Shown wherever the content is scrolled to, or never |
disabled(bool) | It takes no input |
mount(ctx) | The button where it goes: it shows and goes with the scroll. Converting it (.into()) builds its still form, always shown, whose press takes the content to its top at once |
state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them |
- It is a mounted component: after each layout it reads how far the content is scrolled, and shows once that is past the threshold, fading in, and goes, fading out, as the content comes back above it. A page opened scrolled shows it at once.
- A press takes the content to its top with
ctx.scroll_to_top_of(&scroll)(see layout): over the frames that follow, as a wheel’s scroll goes, and at once while motion is reduced or the theme’s smooth scroll is off. A notch of the wheel that comes meanwhile adds to where the content is going, as with any wheel’s scroll. - Where it floats is the app’s to say, as a fab’s is: it is an element, put in a corner of a
Stackover the scroll, in something that gives its shadow room or does not clip (.overflow_visible()). While it is gone it takes no room. - It is a button to tooling, called “Back to top” or by its label, and a stop of Tab while it shows. Once the content is at its top the button is gone and the keyboard’s focus with it: the next Tab goes on from where it stood.
- Parts:
BackToTopPart::Root(what holds the button, whoever draws it: itsenterandexitare how it comes and goes),ButtonandIcon, the last two laid over the theme’s recipe for the root and the icon of an outlined, round button that is an icon alone. State:BackToTopState::Disabled. - In the design it is a circle of 40 on
Backgroundin an edge of 1 inBorder, with the medium shadow and an arrow of 16 inForeground. Under the pointer, pressed and focused it is the outlined button it is made of. - A renderer that draws another has
view.button(), the button with its press attached, to build or to put in what it likes. When it shows, and how it comes and goes, stay the component’s: what a renderer returns is put in the root, which fades, so a renderer of any root fades out as the default one does.
Command Palette
Section titled “Command Palette”A search over the window that finds a command or a place by typing: every command of an editor, the pages of an app, the files of a project.
use lurq::ui::{CommandItem, CommandPalette, icons};
CommandPalette::new(open.clone()) .placeholder("Type a command or search") .group("Suggestions", [ CommandItem::new("Toggle dark mode").icon(icons::MOON).shortcut("Ctrl+D").keywords(["theme"]).on_select(toggle), CommandItem::new("Open DevTools").icon(icons::TERMINAL).shortcut("F12").on_select(devtools), ]) .group("Files", files.iter().map(|file| CommandItem::new(&file.name).icon(icons::FILE).detail(&file.folder))) .label("Commands") .key_hints(true);
// Commands an app fetches as a person types: it keeps every one it was given.CommandPalette::new(open.clone()) .query(query.clone()) .on_query(move |typed| fetched.set(search(typed))) .filter(|_, _| true) .loading(searching.get()) .items(fetched.get().iter().map(|hit| CommandItem::new(&hit.title)));| Builder | |
|---|---|
CommandPalette::new(open) | Shown while the app’s Signal<bool> holds true. Running a command, Escape on an empty input and a press on the veil set it to false |
placeholder(&str) | What the input says while nothing is typed: “Type a command or search” |
item(CommandItem), items(..) | Commands with no group |
group(&str, items) | Commands under a label: “Suggestions”. A group with nothing shown for what is typed is not shown |
filter(Fn(&CommandItem, &str) -> bool) | Which commands are shown while something is typed. By default (matches_every_word) those whose label, detail or keywords hold every word typed, without regard to case, in the order the app gave them |
on_query(Fn(&str)) | Called with what the input will hold at each edit: for an app that fetches its commands. Each handler is called, in order |
query(Signal<String>) | Where the app keeps what is typed. Without one the palette keeps it while it is open, and it is empty when it opens again |
loading(bool), loading_text(&str) | The list ends with a spinner and what loading_text says: “Loading…” |
empty_text(&str) | What the list says when nothing is found: “No results” |
key_hints(bool) | A row at the bottom, under a line, of the keys that work in it: ↑ ↓ to move, ↵ to run, Esc to close |
label(&str) | Its name to what reads the tree: what its input says, unless told |
on_dismiss(Fn()) | A person closed it other than by a command: Escape on an empty input (the engine’s Modal::on_dismiss), a press on the veil. Each handler is called, in order |
dismiss_on_escape(bool), dismiss_on_veil(bool) | Whether Escape on an empty input and a press on the veil close it: both by default. Off, Escape still clears what is typed |
inline(bool) | The panel drawn where it is declared, open or not, without the veil: for a gallery or a test |
state(name, on), style(part, ..), rules(&recipe), id, key | As a button has them. id is the panel’s |
CommandItem::new(label) | A command: what it does, or where it goes |
icon(name), detail(&str), shortcut(&str) | An icon of 16 before the label; a second text after it, muted; the keys that do the same at the end, as a menu writes them (the app binds them) |
keywords([..]) | Words that find it and are not shown |
disabled(bool), on_select(Fn()), id, key | Dimmed, and passed by; called when it is run, after the palette closed; the row’s id and key |
- It stands near the top of the window over the veil, as the engine’s
Modal: the focus goes to its input as it opens and back to what had it as it closes, and Tab stays inside it, as a dialog’s does. - The focus stays in the input. Down and Up move the highlight through the rows that are shown, across groups and round at the ends, past a disabled one, and scroll the list to it; the pointer moves it too, and a row shows it as a menu item shows the keyboard’s focus. Enter runs the highlighted command and closes the palette; a click on a row does the same. Escape clears what was typed, and closes the palette when nothing is. Typing puts the highlight on the first row it shows.
- To what reads the tree it is a
dialogholding acombobox(the input,expanded, with the highlighted command’s label as itsa11y_activedescendant) and alistboxofoptions witha11y_selected. - Parts:
CommandPalettePart::Veil,Panel,Search(the row at the top),SearchIcon,Input(laid over the theme’s input),Key(laid over the Kbd key of the search row’s Escape and of the footer),Results(what scrolls: its most height),List(the room around the rows),GroupLabel,Row(laid over a menu item’s root),Detail,Empty,Status,Footer,FooterHint. The rows are a menu’s items: a theme’s rules forMenuItemstyle them too. States:CommandPaletteState::Loading,Empty. - In the design the panel is 420 wide on
Popoverin an edge of 1 inBorder,radius-xl, the large shadow, 72 from the top of the window overScrim. The search row is 44 high, 14 in, with 10 between the magnifier of 16 inMutedForeground, the input in the body’s type (no edge or fill of its own) and the key, and a line ofBorderunder it. The list is padded 4 and scrolls past 320; a group’s label is 12/500 inMutedForeground, padded 6 and 8; a row is a menu item, 32 high onHighlightwhile it is highlighted. The keys are the theme’s Kbd, in the platform’s names (Enteris ↩ on a Mac), and a row’s shortcut is a Kbd’s plain text, as a menu writes it, with the menu item’sShortcutpart laid over its label. - Its rows, a menu’s items, follow the density as a menu’s do: 24, 32, 40 and 44 high, and the status row with them. The search row and the footer keep their heights.
- A renderer that draws another palette has
view.panel(),view.search(),view.input(),view.key(label),view.results(),view.group_label(label),view.row(index),view.empty_state(),view.status(),view.footer_row()(the key hints),view.veil(panel)andview.modal(panel), withview.shown(),view.command(index)andview.highlighted.
Context Menu
Section titled “Context Menu”A menu of what can be done with an element, opened where the element is pressed with the secondary button or held with a finger: a file in a list, a node of a canvas, selected text.
use lurq::ui::{ContextMenu, MenuItem, icons};
ContextMenu::new(open.clone(), file_row) .item(MenuItem::new("Open").icon(icons::FOLDER_OPEN).on_select(open_file)) .item(MenuItem::new("Rename").icon(icons::PENCIL).shortcut("F2").on_select(rename)) .separator() .item(MenuItem::new("Delete").icon(icons::TRASH).destructive(true).on_select(delete));
// The board's edit menu: the commands of selected text in one row.ContextMenu::new(editing.clone(), editor) .bar(true) .items(["Cut", "Copy", "Paste", "Select All"].map(MenuItem::new));| Builder | |
|---|---|
ContextMenu::new(open, target) | The app’s Signal<bool>, and the element the menu is for, which lays out as it would without it: what asks for the menu sets the signal, and choosing an item, a press outside, Escape and Tab clear it |
item(MenuItem), items(..), separator(), heading(&str) | As a menu has them: icons, shortcuts, checks, radios, submenus, a destructive item |
label(&str) | The menu’s name to what reads the tree: what it is the menu of |
inline(bool) | The panel drawn in place of its element, open or not, and not over the window: for a gallery or a test |
on_dismiss(Fn()), dismiss_on_escape(bool), dismiss_on_outside_press(bool) | As a menu has them |
offset(impl Into<SpacingValue>), collision(CollisionStrategy) | How far its corner is from the point it was asked for, down and toward the end (under its element, from the keyboard), and what it does where the window has no room there (opens up or back, by default) |
bar(bool) | The commands in one row, as the board’s edit menu over selected text has them. Left and Right move between them; a separator is a line down the row, and a heading is left out |
disabled(bool) | The element has no menu now |
state(name, on), style(part, ..), rules(&recipe), id, key | As a button has them. id is the panel’s |
- It opens at the pointer on a press of the secondary button on the element (and on Control and a press on macOS), at the finger on a long press, and under the element from its start on the Menu key or Shift+F10 while the focus is in the element. A press asks for the menu of the innermost element that has one; asked for again on its element, it moves to the new point.
- It stays inside the window: where there is no room down or toward the end of the point, it opens up or back from it. One context menu is open at a time: asking for another closes the first.
- It is a menu: the focus goes to its first item as it opens and back to what had it as it closes, Up and Down move between the items, a letter goes to the item it starts, Enter chooses, a submenu opens beside its item. To what reads the tree it is a
menu, and the element says it has one (a11y_haspopup). - Parts:
ContextMenuPart::Panel(laid over the menu’s panel),Bar(the panel of a bar),BarItemandBarLabel(laid over a menu item’s root and label in a bar); the menu’s and its items’ parts are a menu’s. State:ContextMenuState::Bar. - In the design the menu is a menu at least 220 wide, its corner at the pointer. The bar is a row on
Popoverpadded 3,radius-lg, in an edge ofBorderwith the large shadow; its items are 28 high, padded 10, their labels 13. - Its items follow the density, as a menu’s do. The bar’s items keep their 28: they are the commands of a toolbar.
- The engine places it:
Popup::at(Some((x, y)))(Overlay::at) stands a popup at a point of the window and keeps it inside, which an app may use for a popup of its own.
Sidebar
Section titled “Sidebar”The way round an app, down one side of its window: its groups of places, the one the app is at, a header with the app or the workspace and a footer with who is signed in.
use lurq::ui::{Avatar, Sidebar, SidebarGroup, SidebarHeading, SidebarHeadingVariant, SidebarItem, SidebarTrigger, icons};
let heading = |collapsed| SidebarHeading::new("lurq").description("Workspace").icon(icons::BOX).collapsed(collapsed);let account = SidebarHeading::new("Ivan Zaida") .variant(SidebarHeadingVariant::Account) .description("ivan@lurq.dev") .media(Avatar::new("Ivan Zaida"));
Sidebar::new() .label("Workspace") .header(heading(false)) .header_collapsed(heading(true)) .group( SidebarGroup::new("Project") .item(SidebarItem::new("Overview").icon(icons::HOME).href("/")) .item(SidebarItem::new("Inbox").icon(icons::INBOX).count(12).selected(ctx.route_path() == "/inbox")) .item( SidebarItem::new("Components") .icon(icons::FOLDER) .child(SidebarItem::new("Buttons").icon(icons::FILE)) .child(SidebarItem::new("Inputs").icon(icons::FILE)), ), ) .footer(account) .collapsed(collapsed.get()) .open(open.clone()) .mount(ctx);
// Wherever the app puts it: collapses the sidebar, or opens it over the page on a narrow window.SidebarTrigger::new(collapsed.clone()).open(open.clone());| Builder | |
|---|---|
label(&str) | What the navigation region is called to tooling. “Sidebar” unless told |
header(element), footer(element) | What stays at its top and its bottom while its items scroll: a SidebarHeading, a search. The footer has a line over it. It has one of each: a second call takes the place of the first, where a card’s or a dialog’s footer adds to a row of buttons |
header_collapsed(element), footer_collapsed(element) | What the rail shows in their place: the mark alone, an avatar. Nothing unless told |
group(SidebarGroup), groups(..), item(SidebarItem), items(..) | Groups of items; item and items add to a group of no label |
collapsed(bool) | The rail of the items’ icons, 52 wide: the value of the signal SidebarTrigger turns, collapsed.get(). Its width moves between the two over the theme’s slow duration |
open(Signal<bool>) | On a narrow window, whether it is open over the page. SidebarTrigger sets it; choosing an item, Escape and a press on the veil clear it |
narrow(bool) | Whether it lies over the page whatever the window’s width: it does below the md breakpoint unless told |
state(name, on), style(part, ..), rules(&recipe), id, key | As a button has them. id is the id of the root |
mount(ctx) | Puts it where it goes, keeping which lists are open and the rail’s menus |
build(&theme) | The sidebar as it is at rest in that theme, with no tooltips on the rail and nothing kept: for a gallery or a test. Converted into an element on its own (.into()) it is the same in the theme of what is being rendered |
SidebarGroup | |
|---|---|
new(&str) | A group under a label, written in capitals; an empty one has none |
count(usize) | How many it has, at the end of its label |
action(element) | An action at the end of its label: a small ghost button. The arrow keys of the items pass it by |
collapsible(bool), default_open(bool) | Its label opens and closes it; default_open is how it starts, and the sidebar keeps it from then on |
item(SidebarItem), items(..), key | Its items; key tells two groups of one label apart |
SidebarItem | |
|---|---|
new(&str), icon(name) | Its name, and the icon before it: what the rail shows of it (the first letter of its name where it has none) |
count(usize), badge(element), shortcut(&str) | At its end: a count in the mono family, a Badge, the keys that go to it as Kbd::shortcut writes them |
selected(bool) | It is where the app is: the app’s, following its route |
disabled(bool) | It is dimmed and takes nothing |
on_select(handler), href(path) | What choosing it does: the handler, and with the router feature the path the router goes to. A press, Enter and Space choose |
on_open_aside(handler) | Called when a person asks for it beside what is open, in place of going to it: a press of the middle button, or a press with Ctrl held (Cmd on macOS). An app with tabs opens it in a new one. Such a press does not choose the item |
child(SidebarItem), children(..), default_open(bool) | Nested items, which open and close with their height under it; default_open is how they start, open where one of them is selected unless told |
force(..), id, key | As a button’s. key tells two items of one name apart |
- The items are a tree to the keyboard (
FocusGroup::vertical().one_stop(true).typeahead(true).nested(true), each item at itsfocus_level, one with nested itemsfocus_expanded): Tab stops at it once, on the selected item; Up and Down move through the items shown, nested ones included, Home and End go to the first and the last, and a letter to the item whose name starts with it. Right opens a closed item and on an open one goes to its first nested item; Left closes an open one and on a nested item goes to the item it is in. A group that opens and closes is an item its items are in. On the rail the items are a list, and Right opens an item’s menu. - Collapsed, it is the rail: each item is its icon, says its name (and its keys) in a
Tooltipat its right, and an item with nested items opens them in aMenuthere, the selected one marked. An item whose nested item is selected is the selected one on the rail. - A closed item that holds the selected item is marked as the selected one is, and a closed group that holds it has its label and its chevron in
Foreground: what is selected shows where it is hidden. Tab stops on what marks it, and it is what is scrolled into view. To what reads the tree such an item hasa11y_currentlocation. - On a window narrower than the
mdbreakpoint it lies over the page in aDrawerwithoverlay(true)andscroll(false), as wide as it is beside the page, its header and footer staying while its items scroll; whatevercollapsedsays, it is whole there. Choosing an item closes it first, and then calls the item’s handlers and goes to its path, so a handler that reads the signal sees it closed. - Which item is selected is the app’s: with a router,
.selected(ctx.route_path() == path)on each, and.href(path)to go there. The gallery’s shell does this for its pages. Where the selected item moves (the app selects another: a router, a search, a link of the page), it is scrolled into view, the lists it is in opened; the item selected at the start is scrolled to as well. SidebarTrigger::new(collapsed).open(open)is a ghost button of thepanel-lefticon, called by which way it goes: “Collapse sidebar”, “Expand sidebar”, or on a narrow window “Open sidebar”, “Close sidebar”, each of whichcollapse_label,expand_label,open_labelandclose_labelsay otherwise.narrow(bool)tells it as the sidebar is told;force(..),idandkeyare a button’s.SidebarHeading::new(title)is the row of the header and the footer:description,icon(name)(a mark on the primary fill) ormedia(element)(an avatar),trailing_icon(name),variant(name)(SidebarHeadingVariant::Workspace, the default, orAccount, or a theme’s),collapsed(bool)(the mark alone, for the rail),on_click(|event| ..)andanchor(ElementRef)(a button, from which a switcher’s menu can hang), andstate,style,rules,force,id,keyas a button has them.- Parts:
SidebarPart::Root,Header,Body(what scrolls),Footer(its room at the sidebar’s sides),FooterContent(the line and what is under it),Group,GroupLabel,GroupText,GroupCount,GroupChevron,GroupAction,Item,ItemIcon,ItemLabel,ItemCount,ItemBadge,ItemShortcut,ItemChevron,ItemIndent(one for each level an item is nested),Nested,NestedContent,Heading,HeadingMark,HeadingText,HeadingTitle,HeadingDescription,HeadingTrailing. States:SidebarState::Collapsed,Overlay,Selected,Disabled,Open,Pressable(a group’s label that is pressed, a heading with a handler). Variants of a heading:SidebarHeadingVariant::Workspace,Account. - In the design the sidebar is 260 wide on
Mutedwith a line of 1 inBorderalong its end, padded 8, 2 between rows. The 8 at its sides is its header’s, body’s and footer’s: the body reaches the sidebar’s edge, and at its end it has the lane of the theme’s scroll bar (its width and its inset on either side, 12 with the default bar) where that is more than 8, so that the bar, which is drawn over what scrolls, lies beside the rows and not over them. The rail shows no bar: it scrolls with the wheel and the keys. An item is 32 high (it follows the density: 24, 40 and 44 at compact, comfortable and touch), padded 8 across, 8 between an icon of 16 inMutedForegroundand its name in 13; the selected one is onBackgroundwith an edge ofBorder, its name in the medium weight and its icon inForeground. Under the pointer an item has theStateHoverveil, held downStatePressed, and the ring of the focus is inside it. A group’s label is 11/600 in capitals, 0.6 apart, inMutedForeground, 10 over it and 4 under it. A nested item is 18 further in, after the chevron of 14 of the item it is in. The heading of the header is 44 high with a mark of 28 onPrimary, its title 13/600 over a description of 11 inMutedForeground; the footer’s is under a line of 1 and 48 high, its name in the medium weight. The rail is 52 wide, its items 36 by 32, 4 apart. - It is a mounted component: the tooltips of the rail are mounted, and it keeps which nested lists and groups are open and the anchor and the open signal of each menu of the rail.
- To what reads the tree it is a
navigationcalled by its label, its itemslink(withhref) orbutton, the selected one witha11y_currentpage, an item with nested items witha11y_expanded, and a nested list agroup. - A theme’s renderer (
SidebarRenderer) is given aSidebarViewwith the groups built, the header and the footer as the sidebar is now, andheader(),body(),footer()androot(children)to lay them out;render()is the default.
Menubar
Section titled “Menubar”The menus of an app in a row, File, Edit, View, each opened from its title, as the title bar of a window holds them on Windows and Linux.
use lurq::ui::{Menu, MenuEntry, MenuItem, Menubar, MenubarMenu, icons};
// open: Signal<Option<usize>>, the menu open now; export: ElementRef, exporting: Signal<bool> for a submenu.Menubar::new(open) .label("Application") .menu(MenubarMenu::new("File", [ MenuItem::new("New").icon(icons::FILE).shortcut("Ctrl+N").on_select(move || new_file()).into(), MenuItem::new("Open…").shortcut("Ctrl+O").on_select(move || open_file()).into(), MenuEntry::Separator, MenuItem::new("Export as").submenu(Menu::new(exporting, export).items(["PNG", "SVG", "PDF"].map(MenuItem::new))).into(), MenuEntry::Separator, MenuItem::new("Quit").shortcut("Ctrl+Q").on_select(move || quit()).into(), ])) .menu(MenubarMenu::new("Edit", [ MenuItem::new("Undo").icon(icons::UNDO).shortcut("Ctrl+Z").on_select(move || undo()), MenuItem::new("Redo").shortcut("Ctrl+Y").disabled(true), ])) .menu(MenubarMenu::new("View", [MenuItem::new("Show grid").checked(grid.get()).on_select(move || toggle_grid())])) .menu(MenubarMenu::new("Help", [MenuItem::new("About")]).disabled(!online.get()));Menubar | |
|---|---|
new(open) | Which menu is open, by its index among the bar’s: the app’s Signal<Option<usize>>. A press of an item sets it; choosing in a menu, a press outside, Escape and Tab set it to None; the app may set it too |
menu(MenubarMenu), menus(..) | Menus, after the bar’s others |
label(&str) | The bar’s name to what reads the tree |
disabled(bool) | No menu of the bar can be opened |
state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. force draws the first item that is not disabled, the one Tab stops on. id is the bar’s; its items are {id}-0, {id}-1 and on, and each menu’s panel {id}-0-menu |
MenubarMenu | |
|---|---|
new(title, entries) | A menu called title holding menu items: MenuItems, with MenuEntry::Separator and MenuEntry::Heading between them (.into() each where the list mixes them). Its panel is called by its title to what reads the tree |
disabled(bool) | The menu cannot be opened: its item is dimmed, and the pointer, the arrows and Alt pass it by |
id, key | The id and key of its item on the bar, in place of {id}-{index}; its panel is {id}-menu |
- Its menus are menus, with all their items have: icons, shortcuts, checks, radio items, submenus, disabled and destructive items, separators and headings. One is open at a time.
- The pointer: a press of a title opens its menu, and a press of it again closes it. While a menu is open the pointer coming onto another title opens that one, with no press. Choosing an item, a press outside and Escape close the menu.
- The keyboard: the bar is one stop of Tab (a focus group of one stop). Left and Right move between the titles and go round at the ends, a letter goes to the title that starts with it, and a disabled title is passed by. Down, Enter and Space open the focused title’s menu with the focus on its first item, Up on its last that can be chosen. In an open menu Left and Right close it and open the menu beside it, at its first item: Left in a submenu closes the submenu first, Right on an item with a submenu opens it, and Right on one without goes to the next title from a submenu too. Escape closes the menu and gives the focus back to its title.
- Alt: pressed and let go alone, Alt puts the focus on the first title and underlines the first letter of each title; Alt alone again gives the focus back to what had it, closing a menu that was open. The letters show while Alt is held down too. Alt with a title’s first letter opens its menu from wherever the focus is, and from a menu of the bar opens the other; several titles with one first letter are gone round. On a Mac, where Option with a letter types a character and the app’s menus are the system’s, Alt does neither.
- Under the pointer, focused from the keyboard, or with its menu open, a title is filled with
Highlight, the board’saccent. In the design the bar is 36 tall inBackground, padded 4, with the medium radius and an edge of 1 inBorder, its titles 2 apart; a title is 28 tall, padded 10 at its sides, with the small radius, its text 13/500 inForeground. A disabled title is dimmed. A menu opens under its title from its start, 4 below it. - The engine’s part is
FocusGroup::menu_row(true), which the bar’s row has: a row of elements each of which opens a menu hung from it when it is pressed. While one of those menus has the focus, the Left and Right that nothing in the menu takes close it, with the menus opened from it, and press the element beside it; Alt with a letter and Alt alone act on the first such row of the window. A bar of your own, of buttons and menus, gets the same keys from it. - The bar keeps, for the signal it is given, a signal for each menu kept as one with the app’s, the anchor each menu hangs from, and what Alt shows, while it is in the tree.
- Parts:
MenubarPart::Bar,Item(a menu’s title on the bar: what is pressed, and what is lit),Label(its text). States:MenubarState::Open(the item’s menu is open) andDisabled(the bar, or the item, cannot be opened); an item is resolved in the states of the bar and its own. - To what reads the tree the bar is a
menubar, each title amenuitemcalled by its text witha11y_haspopupmenuanda11y_expanded. - A renderer for
Menubargets aMenubarView:view.bar()is the row with its style, its focus group and its handlers;view.item(index)an item’s behavior with its style,view.label(index)its text, andview.menu(index)its menu, hung from the item, to put after it;view.item_part(index, part)is the style of a part of one item.view.render()builds the bar.
On a Mac an app’s menus belong in the system’s menu bar, which App::set_menu_bar fills (see native menus): there app.menu_bar_support() is MenuBarSupport::Native, and the app shows no Menubar. The native model routes a command by its id (MenuAction::new(id, label), app.on_menu_activate), where a MenuItem calls a handler and has no id; and it has no check or radio item. So one list feeds both from the app’s own description of its commands, built into each:
use lurq::app::{Accelerator, Menu as NativeMenu, MenuAction, MenuBarSupport};use lurq::ui::{MenuItem, Menubar};
struct Command { id: &'static str, label: &'static str, key: Option<&'static str> }const FILE: [Command; 2] = [ Command { id: "new", label: "New", key: Some("n") }, Command { id: "open", label: "Open…", key: Some("o") },];
if app.menu_bar_support() == MenuBarSupport::Native { // menu_bar: the app's MenuBar, its application menu as it likes menu_bar.menus = vec![NativeMenu { title: "File".into(), items: FILE.iter().map(|c| { let action = MenuAction::new(c.id, c.label); match c.key { Some(key) => action.accelerator(Accelerator::command(key)), None => action }.into() }).collect(), }]; app.set_menu_bar(menu_bar); app.on_menu_activate(move |id| run(id));} else { // In the render, the same commands as a drawn bar. let file = FILE.map(|c| { let item = MenuItem::new(c.label).on_select(move || run(c.id)); match c.key { Some(key) => item.shortcut(&format!("Ctrl+{}", key.to_uppercase())), None => item } }); Menubar::new(open).menu("File", file);}Toolbar
Section titled “Toolbar”The tools of what is in front of a person, in a row: the marks of a text, the actions on a table, the commands of a document.
use lurq::ui::{Button, Toggle, Toolbar, ToolbarGroup, ToolbarItem, ToolbarVariant, icons};
Toolbar::new() .label("Formatting") .item(ToolbarItem::from(Toggle::new("Bold").icon(icons::BOLD).icon_only(true).on(bold.get())).shortcut("Ctrl+B")) .item(Toggle::new("Italic").icon(icons::ITALIC).icon_only(true).on(italic.get())) .item(Toolbar::separator()) .item(Button::new("Link").icon(icons::LINK).icon_only(true).on_click(link)) .item(Toolbar::spacer()) .item(ToolbarItem::from(Button::new("Search").icon(icons::SEARCH).icon_only(true)).stays(true)) .overflow(true) .mount(ctx);
// A command bar's groups: a label under each, and the group goes into the menu whole.Toolbar::new() .variant(ToolbarVariant::Plain) .item(ToolbarGroup::new().label("Clipboard").item(Button::new("Paste").icon(icons::PASTE))) .mount(ctx);| Builder | |
|---|---|
Toolbar::new() | An empty bar on a surface, its controls of the small size |
item(impl Into<ToolbarItem>), items(..) | A Button, a Toggle, a ToggleGroup, a Select, a ToolbarGroup, Toolbar::separator(), Toolbar::spacer(), an Element, or a ToolbarItem made of any of them. A ToolbarGroup takes its controls with item and items too |
mount(ctx) | Puts the bar in the tree of ctx’s component: it keeps the menu of what does not fit and the control the focus left. build(theme) and From<Toolbar> for Element draw it once with nothing kept: no tooltips, no menu |
variant(ToolbarVariant) | Surface (the default): the background’s fill and an edge. Plain: neither. Floating: the popover’s fill, an edge and the large shadow |
size(ToolbarSize) | The size of its buttons and toggles (a ButtonSize): Sm by default, as the board draws the bar, so it is 40 high |
overflow(bool) | Where the bar is narrower than its controls, those that do not fit go into a menu behind a More button at its end, the last first. Without it they are cut off |
label(&str) | What the bar is called, to what reads the tree |
more_label(&str) | What the More button is called, in its tooltip and to what reads the tree: “More” |
more_icon(name) | The icon of the More button: more-horizontal by default, a command bar’s chevron |
secondary_command(ToolbarCommand), secondary_commands(..) | A command that is never in the bar, only in the menu of More, after what did not fit; with one, More is always there |
disabled(bool) | Its buttons, toggles and groups of toggles are disabled, and so are the items of its menu and More; an element given as it is is the app’s to disable. State: ToolbarState::Disabled |
state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. force draws the More button; a control is forced with its own. The More button has the id with -more after it, its menu -menu |
ToolbarItem | |
|---|---|
shortcut(&str) | Keys shown in the tooltip of an icon alone and beside its item in the menu |
stays(bool) | The control never goes into the menu |
as_given(bool) | The button or toggle keeps its own variant, size and style over the bar’s: the outline Export of a table’s bar |
ToolbarItem::element(el), in_menu(ToolbarCommand) | Any element: it stays in the bar unless it has a command to stand for it in the menu |
ToolbarItem::stack(items) | Controls one over another in one place of the bar, 2 apart: a command bar’s Cut over Copy. It goes into the menu whole |
A ToolbarCommand is an item of the menu: ToolbarCommand::new(label) with icon, checked (a tick, as a menu item’s), disabled, on_select (each one adds, called in order), id and key.
- The bar gives its buttons its size and makes them ghost ones, and its toggles its size, unless an item is
as_given. A button or toggle that is its icon alone is called by its label and has a tooltip (below it) of its label and its shortcut. - It is one stop of Tab: Tab enters it at the control the focus last left (the first, the first time), and leaves it at once. Left and Right move between its controls, the toggles of a group in it among them; Home and End go to the first and the last; a disabled one is passed by. A field or a select in it keeps its own keys while it is focused.
- With
overflow, a control that does not fit drops out of the bar whole, the last first, and the More button (more-horizontal, after a line) appears at the end. Enter or Space on it opens its menu with the focus on its first item, and Escape gives the focus back to More; the menu has an item for each control that went, in the order of the bar: its label, its icon, its shortcut, a check for a toggle (each toggle of a group, after a line), and its press. A labelled group goes whole, under its label. A select or a field stays unless it hasin_menu. The bar learns what went from the layout (the engine’sShrinkLimit::Dropanddrop_marker), and its menu follows it a pass later. - A labelled group has its line at its end, and no line of the bar stands beside it; the last group of the bar, or the last before its spacer, has none. No line stands between the spacer and More. A command bar is a toolbar of labelled groups under tabs.
- Parts:
ToolbarPart::Root,Item(laid over each button’s and toggle’s root),Slot(a control with the line before it, 2 apart),Separator(laid over a separator’s root),Spacer,Group,GroupItems,GroupLabel,Stack,More,MoreButton(laid over the More button’s root, afterItem). States:ToolbarState::Disabled,Overflowing. Variants:ToolbarVariant::Plain,Surface,Floating. - In the design the bar is padded 4, its controls 2 apart; a button is a ghost one of 32 with an icon of 16; a toggle that is on has the fill of what is picked out; a line of 20 in the border’s color stands between two groups with 4 on either side. On a surface it has the background’s fill, an edge of 1 in the border’s color and the middle radius. A group of a command bar is padded 10 with a line at its end and its label of 10 in the muted foreground under it. A focused control has its ring inside it, where the bar does not cut it off.
- To what reads the tree it is a
toolbarcalled by its label, witha11y_orientation; the More button saysa11y_haspopupanda11y_expanded. - A renderer that draws another bar gets a
ToolbarView:view.slot(index)is a control as the bar lays it out (dropping when it does not fit),view.more()the More button with its menu,view.menu()the menu alone,view.droppedwhich slots went.
In a narrow room. With overflow(true) every control has a form in the menu at the end of the bar: a button,
a toggle (checked), a group of toggles, a labelled group (under its label), a stack, and a select or a field that
was given in_menu. What is kept in the bar is a control that stays, and a select, a field or any element with
no in_menu. What is kept never runs past the bar: a bar narrower than what stays in it (and a bar without
overflow narrower than its controls) scrolls sideways to it, by the wheel, a drag, and the keys, which bring the
focused control into view. A bar that is only built has no menu, and scrolls to all of its controls. The board draws the bar and its overflow menu (Toolbar, Overflow Menu, Table Toolbar) and no narrower form: scrolling to what stays is lurq’s.
Action Bar
Section titled “Action Bar”The toolbar of a selection: over the list whose rows are selected, it says how many are, offers what can be done to them, and clears them.
use lurq::{components::Stack, ui::{ActionBar, Button, icons}};
Stack::new() .child(list) .child( ActionBar::new(selected.get().len()) .action(Button::new("Move").icon(icons::FOLDER_IMPORT).on_click(move_them)) .action(Button::new("Duplicate").icon(icons::COPY).on_click(duplicate)) .destructive_action(Button::new("Delete").icon(icons::TRASH).on_click(delete)) .on_clear(move || selected.set(Vec::new())) .escape_clears(true) .return_focus(list_ref.clone()) .mount(ctx), );| Builder | |
|---|---|
ActionBar::new(count) | The bar of a selection of count: shown while it is more than none |
count_text(&str) | What it says, in place of “3 selected” |
label(&str) | What it is called to what reads the tree, in place of what it says |
action(Button), destructive_action(Button) | Adds an action on what is selected: a round ghost button; one that destroys in the destructive color. actions(..) and destructive_actions(..) add several |
on_clear(handler) | What clearing does: the round button with a cross at the end (none without one), and Escape where it clears. Each one adds, called in order |
escape_clears(bool) | Escape clears the selection while the bar is shown, wherever the focus is, unless what has it took the key |
return_focus(ElementRef) | Where the focus goes as the bar leaves with the focus in it, cleared by its button or by Escape, or emptied by an action: the list it acts on (its first control that takes the focus). Without it the focus leaves with the bar |
mount(ctx) | Puts the bar in the tree of ctx’s component, which keeps whether the focus is in it: return_focus needs it. build(theme) and From<ActionBar> for Element draw it with nothing kept |
side(ActionBarSide) | The edge of the room it is given that it stands at: Bottom (the default) or Top |
clear_label(&str) | What the clear button is called: “Clear selection” |
state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. force draws the clear button; an action is forced with its own. The clear button has the id with -clear after it |
- It is as large as the room it is given and takes no press itself: put it over what it acts on, in a
Stack. The bar stands 16 from the bottom (or the top) of that room, in the middle; it comes in with a fade and a move of 16 from that edge, and leaves the same way as the count goes to none. - It is a toolbar to what reads the tree, called by its label or what it says, and one stop of Tab whose Left and Right move between its buttons.
- What it says is on one line. Where the room is narrower than the bar, it gives way first and is cut with an ellipsis: the actions and the clear button stay whole, at any text size.
- Parts:
ActionBarPart::Root,Bar,Count,Separator(laid over a separator’s root),Action,ActionIcon,ActionLabel,Destructive(laid over a button’s root, icon and label),Clear,ClearIcon. State:ActionBarState::Empty. Variants:ActionBarSide::Bottom,Top. - In the design the bar is 44 high, of the popover’s color, round at its ends, with an edge of 1 in the border’s color and the large shadow, padded 16 before its count and 6 after its clear button, its parts 4 apart. The count is 13/600; a line of 20 with 6 on either side sets it apart; an action is 32 high, padded 10, its icon 14 and its label 13, 6 apart; the clear button is a round 32 with a cross of 15. A phone’s selection bar is the same parts restyled: across the top, 56 high, in the fill of what is picked out.
In a narrow room. A mounted bar wider than its room draws each action that has an icon as its icon alone,
called by its label in a tooltip (ActionBarView::compact); an action with no icon keeps its label, and the
count and the clear button stay. Narrower than its icons too, the actions go, the last first, into the menu of a
More button before the clear button (more_label, “More actions”), and the text ends in an ellipsis only once
every action is in the menu. This is the order of the board’s bar of a phone (Mobile/Selection Bar: the count, the
actions as icons, More). A bar that is only built (converted into an element, or build) cannot measure: it keeps
its labels in any room and cuts its text; mount(ctx) is the one that measures.
Floating Panel
Section titled “Floating Panel”A tool window inside the app’s window, over its content: layers, a color picker, the properties of what is chosen. A person moves it by its title bar, resizes it by its edges and its corner, collapses it to its title bar and closes it.
use lurq::{components::Stack, ui::{FloatingPanel, FloatingPanels, MenuItem}};
// One panel over the canvas. place: Signal<(f32, f32)>, kept with the window.Stack::new() .child(canvas) .child( FloatingPanel::new("Layers") .position(place.clone()) .on_dismiss(move || layers.set(false)) .menu(more.clone(), || [MenuItem::new("Lock all")]) .child(layer_rows) .mount(ctx), );
// Several: the one pressed comes to the front and is the active one; a press on the canvas leaves none active.FloatingPanels::new() .panel(FloatingPanel::new("Layers").default_position((16.0, 16.0)).child(layer_rows)) .panel(FloatingPanel::new("Color").default_position((280.0, 16.0)).child(color)) .mount(ctx);| Builder | |
|---|---|
FloatingPanel::new(title), child(..), children(..) | A panel called by its title, and what it holds under its title bar |
position(Signal<(f32, f32)>), position_controlled((x, y), on_position_change), default_position((x, y)) | Where it stands in its room, from the top start: the app’s signal, which a drag and the keys set; the app’s value, which it is told a move of; or where its own place starts (16, 16 unless told) |
size(Signal<Option<(f32, f32)>>), size_controlled(..), default_size((w, h)), min_size((w, h)) | Its size the same three ways: None is the board’s 240 wide and the height of what it holds; a size of its own makes what it holds scroll. No smaller than 160 by 80 unless told |
on_position_change(handler), on_size_change(handler) | Called with its new place, its new size, when a person moves or resizes it. Not when the app sets the signal. Each call adds |
open(Signal<bool>), default_open(bool), on_open_change(handler) | Whether it shows what it holds or its title bar alone, which its collapse button turns; told when the button turns it |
on_dismiss(handler), close_button(bool), dismiss_on_escape(bool) | Called when its close button or Escape in it closes it: the app takes it away. It has both where it has on_dismiss, unless told |
on_active_change(handler) | Called with whether it is the active panel when a person makes it so or not (see below). Not when the app sets the active panel of a FloatingPanels. Each call adds |
media(element) | Between the grip and the title: an icon, a swatch |
button(icon, label, handler), menu(Signal<bool>, Fn() -> items) | A button of its title bar, before its own; the menu its “more” button opens, of MenuItems |
collapsible(bool), resizable(bool) | Its collapse button; its edges and its corner. Both unless told |
label(&str) | What it is called to tooling: its title unless told |
move_label, resize_label, collapse_label, more_label, close_label | What its grip (“Move”), its corner’s grip (“Resize”) and its buttons are called to tooling. The collapse button keeps its name and says whether it is open |
state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. Its grip is {id}-grip, its corner’s {id}-resize, its buttons {id}-collapse and {id}-close. In a layer its key (its title unless told) tells it from the others |
- It is mounted (
mount(ctx)): it keeps where a drag began, and its place, its size and whether it is open where the app gives no signal. Mounted, it is a layer as large as what holds it (aStackover the content), which lets a press through where the panel is not, with the panel in it at its place. Converted into an element it is drawn where it stands, and a drag does not move it. - A drag of its title bar moves it, the pointer held; a drag of its start edge, its end edge, its bottom row or its corner resizes it. A drag keeps it inside its layer, and no smaller than its least size.
- From the keyboard: its grip, at the start of its title bar, is a stop of Tab, and the arrow keys move the panel by 10, by 1 with Shift. The grip in its corner resizes it with the arrows the same way. Its buttons are pressed with Enter and Space, and Escape anywhere in it closes it. The platforms move a window from the keyboard by its own menu (Alt+Space on Windows) or not at all; a panel inside a window has a grip that takes the focus, as a splitter’s divider does.
FloatingPanelsholds the panels over one content, the one pressed last in front: a press anywhere in a panel, or the focus coming into it, brings it there.- The active panel is
Active, its title inForeground; the others’ are inMutedForeground, as a tool window’s title is while the document has the focus. A press in a panel, or the focus coming into it (Tab), makes it active; a press outside it (on the content the panels float over, on another panel) or the focus going to something outside it makes it not, and the one in front stays in front. A press in its menu, which opens outside it, leaves it active. A panel starts not active; one converted into an element is drawn active, as the board draws it. In aFloatingPanelsone panel at most is active, which the app may hold:active(Signal<Option<Arc<str>>>)is the key of the active panel (itskey, or its title where it has none),Nonewhere none is, set by a press or the focus and shown when the app sets it;on_active_change(Fn(Option<&str>))is told the key, orNone, after it changes by what a person does. Each panel’son_active_changeis told too. - In the design the panel is 240 wide on
Popover, an edge of 1 inBorderinside it, the large radius and the large shadow. Its title bar is 30 high onMutedwith a line of 1 inBorderalong its bottom, 6 in at its start and 4 at its end, 4 between what it holds: a grip of 14 inMutedForeground, the title at 12 and semibold, and buttons of 22 with the small radius, an icon of 14 inForegroundin each, onHighlightunder the pointer. What it holds is padded 4, its rows 2 apart; the row along its bottom is 22 high with a grip of 10 inMutedForeground3 in from the corner. - Parts:
FloatingPanelPart::Root,Header,Grip,Media,Title,Actions,Button,Body,Footer,ResizeGrip,Edge. States:FloatingPanelState::Active,Collapsed,Sized,Resizable,Media. - To what reads the tree it is a
dialogcalled by its label; its grip and its corner’s grip are buttons called “Move Layers” and “Resize Layers”, and its collapse button saysa11y_expanded. - A renderer is given a
FloatingPanelView:view.root()the panel with its place and behavior,view.header(),view.grip(),view.title(),view.actions(),view.body(),view.footer(),view.resize_grip()andview.edges(). - A dock layout is a batch of its own: it would take this panel’s title bar as its tab,
FloatingPanels’ order as the order of its floating windows, and the board’s Dock Drop Indicator (five squares of 32 onPopover, the one under the pointer inInfo) as what a drag of a panel shows over the room it would dock into.
Panel Header
Section titled “Panel Header”The header of a panel that stands on its own in a layout: a side bar’s Explorer, an inspector’s Properties.
use lurq::ui::{MenuItem, PanelHeader, icons};
PanelHeader::new("Explorer") .button(icons::REFRESH, "Refresh", || refresh()) .menu(more.clone(), || [MenuItem::new("Collapse folders")]) .on_close(move || explorer.set(false));| Builder | |
|---|---|
PanelHeader::new(title) | A header called by its title, written in capitals |
media(element) | What stands before the title |
button(icon, label, handler), menu(Signal<bool>, Fn() -> items) | A button at its end, after those it has; the menu its “more” button opens |
on_close(handler) | Shows its close button, and is called on a press of it. Each call adds |
more_label(&str), close_label(&str), level(u32) | What its buttons are called to tooling (“More”, “Close”); the level of the heading it is (2) |
state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them |
- In the design it is 30 high on
Mutedwith a line of 1 inBorderalong its bottom, 10 in at its start and 4 at its end; its title is 11 and semibold in capitals, 0.6 apart, inMutedForeground; its buttons are a floating panel’s. - Parts:
PanelHeaderPart::Root,Media,Title,Actions,Button. State:PanelHeaderState::Media. To what reads the tree its title is a heading of its level.
Dock Layout
Section titled “Dock Layout”Panels an app arranges in groups, splits, floating windows and strips, which a person rearranges: the layout of an editor, its explorer at the start, its documents in the middle and its terminal along the bottom.
use lurq::{ components::Text, core::Signal, ui::{DockLayout, DockNode, DockPanel, DockPlace, DockSide, DockState, icons},};
// The first layout, which the app stores once a person changes it.let mut first = DockState::new( DockNode::row([ DockNode::group(["explorer"]), DockNode::column([ DockNode::documents(DockNode::group(["blur.rs", "theme.rs"])), DockNode::group(["terminal", "problems", "output"]), ]) .shares([0.7, 0.3]), ]) .shares([0.25, 0.75]),);first.show("outline", DockPlace::Hidden(DockSide::Right));
// layout: Signal<DockState>, made once in the component's create.DockLayout::new(layout.clone(), [ DockPanel::new("explorer", "Explorer").icon(icons::FOLDER).child(tree), DockPanel::new("blur.rs", "blur.rs").icon(icons::FILE_CODE).child(editor), DockPanel::new("terminal", "Terminal").icon(icons::TERMINAL).child(terminal), DockPanel::new("problems", "Problems").count(3).child(problems), DockPanel::new("output", "Output").child(output), DockPanel::new("outline", "Outline").child(outline),]).on_change(move |state| storage.set("layout", state.to_text())).on_detach(move |panel| open_in_a_window(panel)).mount(ctx);| Builder | |
|---|---|
new(Signal<DockState>, panels) | The panels, arranged as the signal says; what a person changes is set in it |
controlled(DockState, panels, Fn(&DockState)) | The app’s arrangement, and what it is told of a change, which the layout shows once the app gives it back |
panel(DockPanel), panels(..) | Panels after those it has |
on_change(Fn(&DockState)) | Told the new arrangement after a person changes it (after the signal is set); not when the app sets it. Each call adds |
on_detach(Fn(&str)) | Told the id of a panel let go outside the window: the app may open it in a window of its own. The layout changes nothing by itself |
empty(element) | What the area of documents shows while no document is in it |
label(&str) | What it is called to tooling: “Dock layout” |
maximize_label, restore_label, close_label, more_label, float_label, hide_label, put_back_label, move_left_label, move_right_label, move_top_label, move_bottom_label, strip_label | The words of its buttons and menus: “Maximize”, “Restore”, “Close”, “More”, “Float”, “Hide”, “Put back”, “Move to the left” (and the right, the top, the bottom), “Hidden panels” |
state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. force draws the shown tab of each bar of capitals. Its parts are found by ids after id: {id}-tab-{panel}, {id}-group-{panel} (a group by its first panel) and {id}-body-{panel}, {id}-strip-{panel}, {id}-flyout-{panel}, {id}-maximize-{panel}, {id}-close-{panel}, and {id}-split-{path} with its dividers {id}-split-{path}-divider-{n} |
mount(ctx) | Mounts it: what each panel holds is kept while it moves, and a drag, a strip and the menus work. Converted into an element it is drawn as its state says, and nothing in it is kept or dragged |
DockPanel | |
|---|---|
DockPanel::new(id, title) | A panel the state names id, called title |
icon(name), child(element), children(..) | Its icon (on its strip button, before its document tab’s title); what it holds |
close_button(bool), floatable(bool), hideable(bool), movable(bool) | Whether it closes, floats, hides and moves at all: each unless told |
min_size((w, h)) | Its least size, which the splits that hold it keep: 120 by 80 |
count(u32), dirty(bool), label(&str) | A count after its title in a tab of capitals; the dot of a document with changes not saved; what it is called to tooling (its title) |
on_close(Fn(&DockCloseEvent)) | Called when its close control or its menu’s Close is pressed, before it is taken out of the state; event.prevent_default() keeps it. Each call adds |
The arrangement. A DockState is plain data (Clone, PartialEq, Debug): root, a tree of DockNode::Split (an orientation, its children, each child’s share), DockNode::Group (its panels as tabs, the one shown, the panels hidden from it) and one DockNode::Documents (the area of documents, empty or holding a node); floating, the groups that float with their place and size; and maximized, the panel whose group fills the layout. DockNode::row, column, group, documents, shares and shown write a first layout. A state is changed by what a person does or by the app’s own calls, which return whether anything changed: show(panel, place) and move_panel (a panel the state does not name is not shown until the app shows it), move_group, close, select, put_back, maximize, restore, set_shares, set_float, raise_float. A place is a DockPlace: Tab { of } (a tab of the group that holds of), Beside { of, side } (a new group on that side of it), Edge(side) (a new group along that edge of the layout, a quarter of it), Documents, Float { position, size } or Hidden(side).
- A state is always made valid, never refused (
make_valid(known),valid(known), which every change ends with): a panel the app no longer gives is left out, a panel named twice keeps its first place, an empty group goes, a split of one child folds and a split in a split of its orientation is flattened, shares are brought to at least 0.05 and to a sum of 1, a second area of documents is replaced by what it holds, and amaximizedthat is no docked panel is none. - It is stored as text:
state.to_text()(andDisplay) writes it in a readable form,row(0.25 group("explorer") 0.75 column(…)), andDockState::parse(&text)(andFromStr) reads it back, orNonefor text that is not the form; with thepersistent_storagefeature it is a value of the app’s storage (ctx.set_persistent_value("layout", state)), stored as that text. A state read back is made valid by the layout as any other. - A group in the area of documents has the documents’ tabs, in the board’s compact bar (32 high, titles of 12, crosses of 12 on every tab). A group of one tool panel has the panel’s header: its title in capitals, its menu and its close. A group of several has tabs in capitals with a maximize (or restore) and a close at its end. The rule is the board’s: the editor’s documents, the explorer’s header, the terminal’s three tabs.
- What a panel holds is kept while it moves: to another group, floating and back, hidden and shown, maximized and restored, and while a split is dragged. What it holds is mounted in the layout by the panel’s id, wherever it is shown, and kept offstage while it is not (a tab not shown, a panel hidden): what is typed in it, its caret, where it is scrolled, what is open in it, and the focus in it, which follows it. What it holds is built when the app builds the layout, not when the layout renders for a drag.
- A drag: a tab, a header or a floating group’s title bar dragged shows the indicator over the group under the pointer (its middle and its four sides) and a square at the middle of each edge of the layout; the zone under the pointer is lit and where the panel would land is laid over the layout. Let go on a zone, it lands there: the middle makes it a tab of the group, a side a group beside it, an edge a group along the layout’s edge. Let go over nothing, it floats there, if it may float; outside the window,
on_detachis told and nothing moves. Escape gives the drag up and nothing moves. A whole group is dragged by its bar’s empty room. A press that moves less than 4 is a press. - From the keyboard and from a menu: the menu of a tab (the secondary button, the Menu key or Shift+F10 on it) or of a header’s More has what a drag does, Move to the left, the right, the top and the bottom (along that edge of the layout), Float, Hide (into the strip of the nearest edge), Maximize or Restore, and Close. F6 and Shift+F6 go from the group with the focus to the next and back, focusing its body. In a bar of capitals the arrows go between the tabs and Enter or Space shows one.
- A strip at an edge has a button for each panel hidden there. A press shows the panel over the layout beside the strip, with its header’s Put back (which puts it back in its group) and its close; a press outside it or Escape hides it again.
- Floating groups are floating panels over the layout; their place and size are written to the state when a move or a resize ends.
- An area of documents with nothing in it shows what
empty(..)gives. - The layout fills what holds it, which is to give it a size (a window’s root, a column that grows). A panel’s body is the room its group leaves under its bar; what the panel holds pads and scrolls itself (a
ScrollVerticalthat fills it).DockPanel::id()andtitle()read a panel back. Two layouts in one component have their ownkeyorid. - In the design the layout is on
Backgroundin an edge of 1 inBorderwith the large radius. A bar of capitals is 30 high onMutedwith a line of 1 inBorderalong its bottom, 4 in at its end; its tabs are 12 in at either side and 6 between what they hold, their titles 11 and semibold in capitals 0.6 apart inMutedForeground, the one shown inForegroundwith a line of 2 inForegroundunder it; a count is mono 11; its buttons are 22 with the small radius and an icon of 14 inForeground, onHighlightunder the pointer. A strip is 30 across onMutedwith a line of 1 inBorderon its inner side, 6 in along it and 4 between its buttons of 22. The indicator’s zones are squares of 32 onPopoverin an edge of 1 inInputwith the small radius and the large shadow, the one under the pointer filled and edged inInfo; where the panel lands is laid over inInfoMutedat 0.7 with an edge of 1 inInfo. - Parts:
DockLayoutPart::Root,Group,Bar,Tab,Label,Count,Actions,Button,Body,Empty,Strip,StripButton,Flyout,Preview,Zone. States:DockLayoutState::Selected(a tab shown, a strip button whose panel is shown),Hot(a zone under the pointer),Vertical,Left,Right,Top,Bottom(the edge a strip stands along),Maximized. - To what reads the tree the layout is a
groupcalled by its label, each group agroupcalled by the panel it shows, a bar of capitals atablistoftabs that saya11y_selected, a strip atoolbarcalled “Hidden panels” of buttons called by their panels’ titles that saya11y_expanded, and a panel shown from a strip adialog; the splits are splitters. - A renderer is given a
DockLayoutView: the element the default renderer built, andview.part(..).
Splitter
Section titled “Splitter”Panes that share a room by the dividers between them, which a person drags: the side bar, the editor and the terminal of a window.
use lurq::ui::{Orientation, Splitter, SplitterPane};
// layout: Signal<Vec<f32>>, saved with the window.Splitter::new() .sizes(layout.clone()) .pane(SplitterPane::new(files).length(240.0).min(160.0).max(480.0).collapsible(true).label("Files")) .pane(SplitterPane::new( Splitter::new() .orientation(Orientation::Vertical) .pane(SplitterPane::new(editor).min(120.0)) .pane(SplitterPane::new(terminal).length(160.0).min(80.0).collapsible(true)) .mount(ctx), )) .pane(SplitterPane::new(outline).share(0.2).min(100.0)) .on_resize_end(|sizes| save(sizes)) .mount(ctx);
// The board's Resizable: a grip on each divider, in a box of its own.Splitter::new().grip(true).framed(true).pane(sidebar).pane(content);| Builder | |
|---|---|
Splitter::new(), orientation(Orientation) | Panes side by side (Horizontal, the default), or one over the other (Vertical). SplitterOrientation is a name of ui::Orientation |
pane(SplitterPane), panes(..) | A pane after the others, with a divider before it |
SplitterPane::new(content) | A pane holding content, laid out in its whole width from its top: a height of Dimension::Pct(100.0) fills it |
SplitterPane::length(px), share(0..1) | How large it is to begin with: pixels it keeps as the splitter grows and shrinks, or a share it keeps. A pane with neither takes the rest; where all have one, the last does |
SplitterPane::min(px), max(px) | The least and the most it is |
SplitterPane::collapsible(bool) | It closes when a divider is dragged under half its least size, and opens by a drag back, a double press on the divider (a finger’s double tap) or Enter. The pane that takes the rest does not close |
SplitterPane::label(&str), id(..), key(..) | What it is called: the divider after it is called so to tooling. The id of the pane’s element, and what tells it apart where panes come and go |
SplitterPane::disabled(bool) | It keeps its size: no divider beside it moves it, by the pointer or the keys, and it does not close |
sizes(Signal<Vec<f32>>) | The sizes of the panes, the app’s: pixels along the splitter as a divider last left them, 0 for a closed pane, written as a divider moves and once it is first laid out |
on_resize(handler) | Called with the sizes each time a divider moves: while it is dragged, and for each key |
on_resize_end(handler) | Called with the sizes once a divider has moved: let go after a drag, or moved by a key, a double press or Enter |
step(px), large_step(px) | What an arrow key moves a divider by, and with Shift: 10 and 50 |
grip(bool) | A grip in the middle of each divider |
framed(bool) | A box of its own: a fill, an edge and round corners, as the board draws its specimens |
label(&str) | What a divider is called where the pane before it has no label |
mount(ctx) | Mounted where it is declared: it keeps its sizes where the app gives it no signal, and shows the sizes the app sets in the signal from outside |
disabled(bool), state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. force draws the dividers; id is the root’s, and the dividers are {id}-divider-{n} |
- A drag holds the pointer: the divider follows it wherever it goes, in the window and out of it, the cursor is the resizing one over the divider and for the whole drag, and no text is selected by it. A double press puts the divider back where it began, or opens the closed pane beside it. A closed pane is inert (
.inert, see Focus And Keyboard Navigation): what is in it stays mounted and takes neither the focus nor the pointer. - A divider is a stop of Tab. The arrow keys of its orientation (Left and Right across, Up and Down one over the other) move it by a step, with Shift by a larger one; Home and End take the pane before it to its least and most size, and Enter closes and opens the collapsible pane beside it.
- The panes say what gives way when the window grows or shrinks: one of pixels keeps them, one of a share keeps its share, and the pane given no size takes the rest. No open pane is made smaller than its least size while there is room: where the rest would be, the panes nearest it give way down to theirs.
- A splitter measures its room before the frame is painted (
ElementRef::observe_rect_before_paint): its first frame shows the panes at the sizes that fit the room, a pane whose share is under its least size at its least size, each divider at the edge of its pane, and nothing moves in the frames after. A splitter in a pane settles in that frame too. - Converted into an element, a splitter keeps its sizes while what holds it does not render again, unless it is given
sizes; mounted, it keeps them, and an app that setssizesfrom outside (to restore a layout) sees the panes take them. Pixels set from a saved layout are the pane’s pixels, and a pane of a share takes the share its pixels were of the room they were saved in. - A drag renders nothing again while it moves: the panes are resized by sizes their element refs are given (
ElementRefMut::set_size), and what is in them is only laid out again at the next pass. Nor does letting it go: tooling reads where it stands from the divider at once (ElementRefMut::describe). - Parts:
SplitterPart::Root,Pane,Handle(the room around a divider’s line that takes the pointer and the focus),Line,Bar(the wider line under the pointer, dragged and focused),Grip,GripIcon. States:SplitterState::HorizontalorVertical,Framed,Disabled. - In the design a divider is a line of 1 in the
Bordercolor; under the pointer and focused from the keyboard it is 3 wide inRing, and dragged inPrimary. The room that takes the pointer is 12 across the line, over the edges of the panes beside it. The grip is 12 by 20 (20 by 12 across a vertical splitter), round by the small radius, inBorder, with a grip icon of 10 inForeground. Framed, the splitter has theBackgroundfill, an edge of 1 inBorderand the large radius. - To what reads the tree a divider is a
separatorthat can be focused, witha11y_orientation(that of its line),a11y_valuenow(the pixels of the pane before it),a11y_valuemin,a11y_valuemax(where it has a most) and the name of the pane before it, or the splitter’slabel.a11y_valuenowfollows the divider as it is dragged and moved by the keys. - Splitters nest, one orientation in the other: a pane holds a splitter of its own.
- A renderer that draws another splitter is given the view:
view.part(..),view.thickness()(the room between two panes),view.sizes(), andview.render()the default.
A room that changes. A splitter follows its room: panes that a narrow room took room from have it back when the room grows, as a splitter first laid out at that width has them, until a person drags a handle. A dock layout follows through its splitters.
Property Grid
Section titled “Property Grid”An inspector: the names of what is selected and the editors of their values, in categories that open and close. The position and the size of a shape on a canvas, its fill, its opacity.
use lurq::{components::SelectOption, ui::{Property, PropertyCategory, PropertyGrid}};
PropertyGrid::new() .title("Properties") .category( PropertyCategory::new("Transform") .property(Property::xy("Position", x.clone(), y.clone())) .property(Property::pair("Size", ("W", w.clone()), ("H", h.clone()))) .property(Property::number_with("Rotation", rotation.clone(), "°").stepper(true).default(0.0)), ) .category( PropertyCategory::new("Appearance") .property(Property::color("Fill", fill.clone())) .property(Property::slider("Opacity", opacity.clone(), 0.0, 100.0, "%")) .property(Property::number("Radius", radius.clone()).default(8.0)) .property(Property::choice("Blend", blend.clone(), [SelectOption::new(0, "Normal"), SelectOption::new(1, "Multiply")])) .property(Property::toggle("Visible", visible.clone())), ) .on_change(|id| save(id)) .mount(ctx);| Builder | |
|---|---|
PropertyGrid::new() | A grid with no category yet |
category(PropertyCategory), categories(..) | Adds categories after those it has |
title(&str), trailing(Fn() -> Element) | The header over the categories, its title in capitals, and its buttons at its end |
name_width(f32) | The width of the names, 84 unless told: where the mounted grid’s divider starts |
read_only(bool), disabled(bool) | Every value read and not changed; or nothing takes input, dimmed |
full_width(bool) | As wide as what holds it, in place of 300: an inspector’s column |
height(impl Into<Length>) | Its rows scroll in it: a long inspector’s. Mounted, it builds only the rows near its view |
label(&str) | What it is called to tooling: its title, else “Properties” |
on_change(Fn(&str)) | Called with the id of a property a person changed (its id, else its name), after its value is set; not when the app sets a value |
mount(ctx) | The grid mounted where it is declared: it keeps which categories are open and where the divider is, Escape gives an editor’s focus back to its row, and a text is told as the focus leaves it |
state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. With an id, a category’s row is <id>-<category>, a property’s <id>-<property>, its editor’s holder <id>-<property>-editor, its reset <id>-<property>-reset, the divider <id>-divider |
Property<V> | |
|---|---|
Property::text(name, Signal<String>) | A text in an input |
Property::number(name, Signal<f64>), number_with(name, value, unit) | A number in a number input, stepped with Up and Down; with a unit written after it (°, %). stepper(true) gives it the board’s stepper: one control of chevrons at the end of its box, its upper half a step up and its lower half a step down |
Property::slider(name, Signal<f32>, min, max, unit) | A slider with the number typed beside it |
Property::toggle(name, Signal<bool>) | A checkbox |
Property::choice(name, Signal<T>, options) | One of the options in a select |
Property::color(name, Signal<Color>) | Its swatch, a press of which opens the color picker in a popover, and its hex typed in a box beside it; a hex is committed with Enter or as the focus leaves it, and one that is no color is put back. eyedropper(true) gives the box an eyedropper at its end, which opens the picker too |
Property::xy(name, x, y), pair(name, (letter, a), (letter, b)) | Two numbers side by side, each with its letter in its box: X and Y in the axes’ colors, or W and H |
Property::custom(name, Fn() -> Element) | Any element as the editor: it has no default and tells the grid nothing |
default(V) | What the reset puts back; while the value is another, the name is marked and the reset is shown. Of the property’s type: a default of another type does not compile |
description(&str), read_only(bool), disabled(bool), id, key | Said of its row to tooling; its value read and not changed; dimmed; what on_change is told and its row’s id; its row’s key |
PropertyCategory::new(title) | A category, open. property, properties add to it; default_open(bool) whether it is open as it is first shown; disabled, id, key (what the mounted grid keeps it open by: its title unless told) |
- Every value is the app’s signal, edited at once by its editor:
ui’s own controls, the input, the number input, the select, the checkbox and the slider, each with the grid’sEditorpart laid over its box, and for a color a swatch and an input. The color row and the stepper are the grid’s own: the board draws them only in its inspector (Property Grid’s Fill and Rotation rows); its Color Field and Number Input are drawn otherwise, a swatch inside the box with an eyedropper and a minus and a plus at the ends. A choice, a box, a color, a slider and a number are told toon_changeas each change is made; a text as it is committed, with Enter, or (mounted) as the focus leaves it after an edit. - To the keys it is a tree (a nested group): Tab enters at one row, Up and Down go between the rows, Right opens a closed category and Left closes an open one or goes from a property to its category, typing a letter goes to the row it starts. Tab or Enter on a property’s row go into its editor, where its own keys work (Up steps a number), and Escape gives the focus back to the row (mounted). A press of a name gives its editor the focus; a press of a category opens or closes it.
- A category opens and closes as an accordion’s item does, over the theme’s base duration and its standard easing, at once where motion is reduced: its rows slide open under its row and what is below moves with them, its rows fade in and out, and its chevron turns. Pressed again on the way, it turns round from where it is; the keys and the focus work all through it, and a closed category’s rows are reached neither by Tab nor by the arrows. In a grid that builds every row, the rows are in a panel whose height runs, as the accordion’s; in a grid with a
height, whose rows are items of a virtual list, each row’s height runs from nothing to its own in its turn, the rows coming into view built as they come, and the rows of a closing category stay, inert, until they have closed. That motion of rows in a virtual list is the one a mounted tree view’s rows have: the two share it. - The divider between the names and the editors is dragged, or moved by 8 with Left and Right while it has the focus (40 with Shift); it is a stop of Tab after the rows, a
separatorto tooling with its value. It moves nothing where the grid is not mounted. - To tooling it is a
treegrid: a category is arowat level 1 witha11y_expanded, a property arowat level 2 called by its name, with its value ina11y_value(“X 120, Y 64”) and its description; its editor is called by the name too (“Position X”), so the name is heard with the value from the row and from the editor alike. A group of labelled controls would say the value only in the editor, and the arrows of a tree need rows. - A grid given a
heightscrolls, its bar in a lane of its own beside the rows (ScrollBarPlacement::Reserved), so no editor, reset or mark is ever under it; one with no height keeps its full width. Mounted, it builds only the rows near its view, as a tree view does: the engine’sFocusRowshold every row shown, so Up, Down, Home, End, PageUp, PageDown, Left, Right and typeahead reach any of them, and the row the focus goes to is built and brought into view. A row’s editor keeps what is half typed while the row is built; scrolled far away, the row is let go. A grid with no height has nothing to scroll and builds every row; so does one a theme’s renderer draws. - Parts:
PropertyGridPart::Root,Header,Title,Category,Chevron,Panel(what opens and closes under a category’s row),Body(its rows, which fade),CategoryTitle,Row,Label(a property’s name),Modified(its mark),Value,Editor(laid over each control’s box),Axis,AxisX,AxisY,Reset,Stepper(a number’s chevrons, a color’s eyedropper),Swatch(a color’s),Divider. States:PropertyGridState::Disabled,FullWidth, and on a category’s or a property’s partsOpen,Modified,ReadOnly,Unavailable. - In the design the grid is 300 wide on
Backgroundwith an edge of 1 inBorderand the large radius. Its header is 30 high onMuted, its title in 11 semibold capitals spaced 0.6 inMutedForeground. A category’s row is 28 high onMutedwith a line under it, its chevron of 14 inMutedForeground6 before its title in 12 semibold. A property’s row is 32 high with a line under it, padded 12 at its start and 8 at its end, its name 84 wide in 12 inMutedForegroundand its editors 8 after it, 6 apart. An editor is 24 high onBackgroundwith an edge of 1 inInput, the small radius, padded 6 across, its text in 12 mono; the letter of a value of two is 11 semibold mono, X inDestructive, Y inSuccess, others inMutedForeground. A number’s stepper is the chevrons of 12 inMutedForeground, 6 from the end of its box. A color’s swatch is 24, the small radius with an edge of 1 inBorder, 6 before its box. A changed value’s name is 12 semibold inForegroundwith a dot of 5 inInfoafter it, and the reset of 13 inMutedForegroundends its row. The board draws no row under the pointer or focused: a row under the pointer is onMuted, a focused one has the focus ring inside it. Rows follow the theme’s density; editors keep their 24. - A renderer that draws another grid has
view.header(),view.category_row(index, entry),view.property_row(category, row, entry),view.divider()andview.categories, each category’s and property’s view with its recipe in its state.
Document Tabs
Section titled “Document Tabs”The open documents of an editor, in a bar across its top: one of them shown, each closed by its control, moved by a drag, and those that do not fit in a menu at the end.
use lurq::ui::{DocumentTab, DocumentTabs, MenuItem, icons};
// shown: Signal<PathBuf>; files: the app's list of what is open.DocumentTabs::new(shown.clone(), files.iter().map(|file| { DocumentTab::new(file.path.clone(), &file.name) .icon(icons::FILE_CODE) .dirty(file.dirty) .pinned(file.pinned) .preview(file.preview)})).label("Open files").on_close(|path| close(path)).on_reorder(|from, to| files.update(|files| { let file = files.remove(from); files.insert(to, file); })).on_keep(|path| keep(path)).on_add(|| new_file()).context_menu(|path| vec![MenuItem::new("Close Others"), MenuItem::new("Copy Path")]).mount(ctx);| Builder | |
|---|---|
DocumentTabs::new(Signal<T>, tabs), optional(Signal<Option<T>>, tabs) | The tabs, of which the one whose value the signal has is shown, or none where it is None: an editor with nothing open. A press of another tab sets the signal |
controlled(value, tabs, on_change), controlled_optional(Option<T>, tabs, on_change) | The app holds which is shown, and on_change is told what it is to be; the bar shows nothing itself |
tab(impl Into<DocumentTab<T>>), tabs(..) | Tabs after those it has. (value, "name") is a tab |
on_change(handler) | Told the new value as a person shows another tab, after the signal is set: &T of a DocumentTabs<T>, &Option<T> of a DocumentTabs<T, Option<T>>. Not when the app sets the signal, nor for a press of the tab shown |
on_close(Fn(&T)) | Told the tab a person closes, after its own handlers: its close control, a press of it with the middle button, Ctrl+W (or Cmd+W) while it is focused, or while it is shown with shortcuts on, but a pinned tab, which no key closes. The app takes it out, and says which is shown next where it was the one shown |
on_reorder(Fn(usize, usize)) | Told that a person moved the tab at the first index to the second, both counted in the tabs as they are before and after: tabs.insert(to, tabs.remove(from)). By a drag along the bar, and by Ctrl+Shift+PageUp and PageDown on a focused tab. A pinned tab moves among the pinned ones, another among the others. The bar moves nothing itself |
on_drag_away(Fn(&T, &DragEvent)) | Told while a person drags a tab away from the bar (farther from it than it is high, or outside the window), of mounted tabs: each move, and the release, whose drop_result is Some. While it is away the bar marks no place and moves nothing; where it goes is the app’s, as a dock layout docks it. Each call adds |
on_add(Fn()) | A press of the new tab button after the tabs, which is there once this is given |
on_keep(Fn(&T)) | A double press of a preview, or a finger’s double tap: the app keeps the document open as a tab that is no preview |
context_menu(Fn(&T) -> Vec<MenuItem>) | The commands of a tab’s context menu, opened by a press of the secondary button, a long press, the Menu key or Shift+F10 on a mounted bar |
label(&str) | What the tabs are called to what reads the tree: a tablist of that name |
close_label(&str), add_label(&str), more_label(&str) | What the close control is called before the tab’s name (“Close blur.rs”), the new tab button and the More button: “Close”, “New tab” and “Show the hidden tabs” unless told |
mount(ctx) | Puts it where it goes: it keeps which tabs did not fit and the menu of them, a tab being dragged, and each tab’s context menu. Built on its own (build, .into()) every tab is in the bar whether it fits or not, with no drag and no context menu |
DocumentTab::new(value, name) | A tab. icon(name) an icon before its name, dirty(bool) a document not saved, pinned(bool) a square of the pin at the start with no close control, preview(bool) its name in italics, on_close(Fn()) its own handler, called before the bar’s, disabled, id (its close control is {id}-close, its item in the menu {id}-item) and key (what the focus follows it by when it moves: its name and how many before it have the same unless told) |
shortcuts(bool) | Whether the editor’s keys work from anywhere in the window, the focus in the document or elsewhere: on unless told otherwise |
disabled(bool), state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. force draws the tab Tab stops on; the bar’s buttons have ids after its own, {id}-add and {id}-more |
- The tabs are one stop of Tab, at the one shown. Left and Right move the focus between them, and Space and Enter show the one focused: a document is not opened by an arrow. The new tab button and the More button are stops of their own.
- A tab under the pointer, or holding the focus, shows its cross whole; another’s is at half, and a document not saved shows a dot in its place, which the cross takes the place of under the pointer. The close control is no stop of Tab: Ctrl+W closes the tab focused, and the focus goes to the tab after it, or before it where it was the last.
- The editor’s keys are heard wherever the focus is, as window tabs hear theirs: Ctrl+Tab and Ctrl+Shift+Tab show the next tab and the one before, round at the ends, as Ctrl+PageDown and Ctrl+PageUp do on Windows and Linux; Ctrl+W (Cmd+W on macOS) closes the tab shown, but a pinned one; Ctrl+Shift+PageDown and PageUp move it among its kind. With the focus on a tab, they act on the focused tab’s own keys first (Ctrl+W closes that one) and the focus follows the tab shown.
shortcuts(false)turns them all off. Where the window’s title bar has window tabs with their keys on too, a press is the documents’ and the window’s pass it by; an app that wants the window’s to have the keys turns these off. - A drag of a tab along the bar marks where it goes with a line of 2 in
Primaryat the edge of the tab it goes before (or after the last), and the dragged tab is dimmed; let go,on_reorderis told. A press that moves less than 4 is a press. Ctrl+Shift+PageUp and PageDown move the focused tab one place, and the focus stays on it. - Mounted, the tabs that do not fit leave the bar from its end, the last first, but the one shown and the pinned ones. The More button at the end says how many it holds and opens a menu of them; a tab chosen there is shown, and is in the bar from then on with the focus on it. A tab pressed keeps the focus as it becomes the one shown, and a tab closed leaves it on the tab that takes its place.
- A name longer than its room ends in an ellipsis: a tab is 240 wide at most, and its close control keeps its room.
- The bar is a row of the density’s height: 38 at the default, the steps of a row from it (
ui::ROW_STEPS); the pinned tab and the new tab button stay square. - To what reads the tree the bar is a
tablist(itslabel), each tab atabcalled by its name witha11y_selected, a pinned one too; the close control is called “Close” and the tab’s name; the More button saysa11y_haspopupmenuand whether it isa11y_expanded. - Parts:
DocumentTabsPart::Root,Bar(the box under the tabs, onBar, with the line the tab shown covers),List,Tab,Icon,Label,Close,CloseIcon,Dirty,Add,AddIcon,More,MoreLabel,MoreIcon. States of a tab:DocumentTabsState::Selected,Dirty,Pinned,Preview,Disabled,Dragged,DropBefore,DropAfter; of the bar,Overflowing. - In the design the bar is 38 high in
Mutedwith a line of 1 inBorderalong its bottom. A tab is padded 12 at its start and 8 at its end, its icon of 14, its name of 13 and its close control of 20 (the small radius, a cross of 13) 8 apart, a line of 1 inBorderat its end; its icon and name are inMutedForeground. The tab shown isBackgroundwith a line of 2 inPrimaryalong its top, over the bar’s line, its icon, name and cross inForeground. The close control under the pointer isSecondaryHover. The dot of a document not saved is 8 inForeground. A pinned tab is a square of 38 with its pin. The new tab button is a square of 38 with a plus of 16 inForeground; the More button is padded 10 with a line at its start, its count of 12 and a chevron of 14 inMutedForeground, 4 apart. - A renderer that draws other tabs is given the view:
view.tabs(each tab’s name, icon and states),view.dropped,view.part(..),view.tab_part(index, ..),view.tab(index),view.list(),view.add(),view.more()andview.render()the default.
Status Bar
Section titled “Status Bar”The bar along the bottom of a window, which says what state the app is in: the branch, the problems, what is being done at its start; where one is in a document at its end.
use lurq::ui::{StatusBar, StatusBarVariant, StatusItem, StatusItemVariant, icons};
StatusBar::new() .label("Editor status") .leading([ StatusItem::new("feat/design-system").icon(icons::BRANCH).variant(StatusItemVariant::Primary).priority(2), StatusItem::new("3").icon(icons::WARNING).tooltip("3 warnings").on_select(|| show_problems()), StatusItem::new("Indexing").progress(0.55), ]) .trailing(["Ln 42, Col 7", "UTF-8", "Rust"]) .mount(ctx);
// Debugging: the whole bar in a tone.StatusBar::new().variant(StatusBarVariant::Warning).leading(["Paused on a breakpoint"]);| Builder | |
|---|---|
StatusBar::new() | An empty bar in the neutral tone |
leading(items), trailing(items) | Items at its start and at its end, after those it has there. A &str is an item of that text |
variant(StatusBarVariant) | The tone of the whole bar: Neutral (the default), Primary, Info, Success, Warning, Destructive. Each item is in it unless it has its own |
drops_first(StatusRegion) | The end that gives way first where the bar is too narrow: Trailing (the default) or Leading |
label(&str) | What the bar is called to what reads the tree |
mount(ctx) | Puts it where it goes with the tooltips of its items, which keep their timers. Built on its own it has none |
StatusItem::new(text) | An item: its text, which is its name to what reads the tree. icon(name) an icon before it, icon_only(bool) the icon alone, variant(StatusItemVariant) its tone, tooltip(&str), progress(0..1) a rail after its text, priority(i32) how long it stays in a bar too narrow (the lower leave first, 0 unless told), disabled, id, key |
StatusItem::on_select(Fn()) | Called when it is pressed, by a click, Space or Enter: an item with a handler is a button, one without says what it says. Each one adds |
state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. force draws the first pressed item |
- The items that are pressed are one stop of Tab, at the first of them; Left and Right move between them and pass the others by.
- Where the bar is too narrow its items leave it whole, those of the lowest priority first; of one priority, the end
drops_firstsays before the other, each from its end. An item that left is no stop of Tab. A text is 240 wide at most, and ends in an ellipsis. - A tone is the muted fill of its color, the item’s text and icon in the color:
DestructiveMutedandDestructive.Primaryis the primary fill and its foreground. A pressed item under the pointer is under the hover veil (StateHover), held down underStatePressed, whatever its fill. - The bar is 26 high whatever the density: it is a bar, as the toolbar and the menubar are, not a row.
- To what reads the tree the bar is a
status(itslabel), each item called by its text, an icon alone too; an item with progress saysa11y_valuenowwhere it is pressed. - Parts:
StatusBarPart::Root,Item,Icon,Label,Track,Fill. States of an item:StatusBarState::Pressable,Progress,Disabled; variants:StatusBarVariant(StatusItemVariantis the same). - In the design the bar is 26 high in
Mutedunder a line of 1 inBorder. An item is padded 8, its icon of 13 and its text of 12 inForeground5 apart. The item with progress has its text inMutedForegroundand, 8 after it, a rail 72 by 4 of theInputcolor, round, its part done inForeground. The branch is in thePrimaryfill. - A renderer that draws another bar is given the view:
view.entries(each item’s text, its end, whether it is pressed and its order),view.part(..),view.item(index)(an item, built, as it leaves the bar) andview.render()the default.
Window Chrome
Section titled “Window Chrome”The title bar of a window the app draws itself, as Windows, macOS, GNOME and KDE draw theirs: the app’s icon, the title, room for the app’s own controls (a menubar, tabs, a search) and the window’s controls.
use lurq::ui::{MenuItem, Menubar, MenubarMenu, WindowChrome, WindowControls, WindowPlatform};
// In the app's root component: open is a Signal<Option<usize>> of the menubar.WindowChrome::new() .title("Untitled — Notes") .leading(Menubar::new(open).menu(MenubarMenu::new("File", [MenuItem::new("New"), MenuItem::new("Open…")]))) .controls(WindowControls::new().close_label("Close Notes").on_close(|| save_draft())) .content(document) .mount(ctx);
// The bar of another platform, as a picture: a gallery, a test.WindowChrome::new().platform(WindowPlatform::Kde).title("Notes");| Builder | |
|---|---|
WindowChrome::new() | The chrome of the platform the app runs on (WindowPlatform::current()), with the window’s icon and its three controls |
platform(WindowPlatform) | Windows, Macos, Gnome or Kde: the bar’s look and order, in place of the platform’s own |
title(&str) | The window’s title: in the bar (not a bar with tabs) and given to the window, where the system shows it. On one line, ending with an ellipsis where it has no room |
icon(impl Into<WindowChromeIcon>), label(&str) | The app’s icon where the platform shows one (Windows, KDE): by default the window’s own, the image the app set as the window’s icon, or the box where it has none; a name of the theme’s icons; an image of the app’s (ImageData, with the raster feature); or None. The bar’s name to what reads the tree, its title unless told |
leading(element), trailing(element) | The app’s own at the start of the bar (after the icon, after the lights on macOS) and at its end (before the controls). A press there is theirs: it does not drag the window |
tabs(element) | Window tabs in the bar: the bar of the board’s chrome with tabs, higher, with the app’s icon and title before the tabs (where it has them) and no line under it, the tabs on its bottom edge so that the selected one runs into the content |
controls(WindowControls) | The window’s controls: minimizable(bool), maximizable(bool), their names minimize_label, maximize_label, restore_label and close_label, and on_close(Fn()), called before the window is asked to close |
content(element), overlay(element), overlays(..) | What the window shows under the bar, and layers over the whole of it, as the engine’s chrome has them |
mode(WindowChromeMode), resize_handles(ResizeHandlePolicy), border(ChromeBorderPolicy) | The engine’s chrome: when the app draws it (Windows and macOS by default), the zones along the edges that resize the window, the line around it |
mount(ctx) | The window: the engine’s WindowChrome around the content, with this bar as its title bar |
state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. state gives the still form WindowChromeState::Inactive and Maximized; force draws the close control under the pointer or held, and on macOS the lights’ glyphs. id is the bar’s: its icon is {id}-icon, its title {id}-title, its controls {id}-minimize, {id}-maximize and {id}-close |
- Mounted, it is the window’s frame. The window loses the system’s title bar, and the bar drags the window from wherever nothing in it takes the press, a double press maximizes and restores it, and a right press shows the system’s menu of the window (Restore, Move, Size, Minimize, Maximize, Close) where the system has one, on Windows (
WindowHandle::show_system_menu). The edges resize it. The three controls are the window’s to the system: each is marked with the engine’s.window_control(..)(components), in whichever platform’s look the bar is drawn, so on Windows 11 the pointer resting on the maximize control opens the system’s snap layouts over it. The controls are still under the pointer, held and pressed as any element is, and it is they that act on the window. A bar drawn as a picture marks none. - The bar’s icon is the window’s: the image the app gave the window (
WindowHandle::set_icon, orwith_iconas it opens), drawn at the icon’s size, 16, and drawn again as the app changes it; the board’s box where the window has none. A bar drawn as a picture shows the icon of the window it is drawn in, as the gallery’s pages show the gallery’s.icon(..)puts a glyph of the theme’s in its place (WindowChromeIcon::Glyph, from a name), an image of the app’s (WindowChromeIcon::Image, from anImageDatathe app keeps, so that it is uploaded once), or none (None). An image wants therasterfeature (on withimage); without it the window’s icon is not drawn and the box is. Its id is{id}-icon. - The controls act on the window: minimize, maximize and restore, and close asks the window to close (
WindowHandle::request_close), which an app that must confirm first hears withctx.window().on_close_requested(..). A press on a control is the control’s, never a drag. - The bar is drawn as the window is: a window that is not the one in front has its title, its icon and its glyphs in
MutedForegroundand grey lights on macOS (WindowChromeState::Inactive), and a maximized one’s middle control restores it, namedrestore_label(Maximized). A mounted chrome reads both from the window and is drawn again as they change; the still form takes them fromstate(..). - An app’s menus go in the bar’s leading room:
leading(Menubar::new(open)..). Its titles open their menus over the window; a press on them is theirs, and the bar around them still drags the window. A menubar draws a bar of its own, onBackgroundin an edge; on the title bar’s fill it is laid over with no fill, no edge and no padding:.style(MenubarPart::Bar, |s| s.background(Color::new(0, 0, 0, 0)).border(Border::inside(0.0, PaletteColor::Border)).padding_x(0.0)). On macOS an app’s menus belong in the system’s menu bar (App::set_menu_bar), and the leading room holds what else the app puts there. - Converted into an element on its own it is the still form of itself: the window, its bar over its content, as a picture, with controls that act on no window (
on_closeis still told). A gallery shows the four platforms side by side so. - One component, four renderers:
view.windows(),view.macos(),view.gnome()andview.kde(), whichview.render()chooses by the platform. A theme’s renderer may draw every platform as one of them, or another bar fromview.bar(),view.icon(),view.title(),view.balance(),view.leading(),view.trailing(),view.tabs(),view.drag_room(),view.control(WindowControl)andview.controls(). - In the design the bar is on
Bar(white in the light palette,Muted’s color in the dark) with a line of 1 inBorderunder it, its title 13 inForeground. With tabs the line is under the tabs (WindowChromePart::Line), and the selected tab stands over it, open to the content:- Windows: 36 high, 12 in at the start; the box icon 16 and the title 13/500, 8 apart, at the start; three controls 46 by 36 at the end, a minus 16, a square 12 (two squares 13 while maximized) and a cross 16 in
Foreground; minimize and maximize onSecondaryHoverunder the pointer, close onDestructivewith its cross inDestructiveForeground. - macOS: 36 high, 12 in; the lights 12 across, 8 apart, at the start, close, minimize and zoom, in the system’s red
#FF5F57, yellow#FEBC2Eand green#28C840with a rim of#0000001F, grey (Input) in a window that is not in front, showing a cross, a minus and a plus of 8 in#00000099under the pointer on any of them; the title 13/600 in the middle of the bar. - GNOME: 44 high, 10 in; the title 13/600 in the middle; round controls of 24, 8 apart, on
SecondaryHover, a minus 14, a square 10 and a cross 14; close onDestructive. - KDE: 32 high, 8 in at the start and 6 at the end; the box icon 16 at the start, the title 13/400 in the middle; round controls of 22, 6 apart, a chevron down 16, a chevron up 16 and a cross 14; close on
Destructive. - A bar with tabs is 40 high (44 on GNOME, 38 on KDE), and has the icon and the title before its tabs, no line under it. The board draws no title there; Ivan wanted the app named in its window (2026-11-17). On Windows the controls keep the top 36 of it; elsewhere they are in its middle.
- The bar’s height is its recipe’s, with tabs or not: the content of a mounted chrome starts under the height the recipe gives
WindowChromePart::Barin the bar’s states and on its platform, so an app’s rule makes a bar with tabs 36 high:.rules(&Recipe::new().when(Selector::new().state(WindowChromeState::Tabs), WindowChromePart::Bar, |s| s.height(36.0))), or the same in its theme. A height that is no number of pixels is the board’s. - The window is
Backgroundin an edge of 1 inBorder, its corners 8 on Windows, 12 on macOS and GNOME, 6 on KDE (the still form; a window’s own corners and shadow are the system’s). - Where the board is silent: a pressed control is as it is under the pointer, close
DestructiveHover; GNOME’s round controls have a veil over their fill under the pointer (StateHover) and a stronger one held (StatePressed), so they grow stronger in the light appearance and the dark alike, KDE’s areSecondaryHoverunder the pointer and that with theStatePressedveil held; GNOME’s maximized control shows two squares, KDE’s keeps its chevron; a window not in front is muted on every platform.
- Windows: 36 high, 12 in at the start; the box icon 16 and the title 13/500, 8 apart, at the start; three controls 46 by 36 at the end, a minus 16, a square 12 (two squares 13 while maximized) and a cross 16 in
- Parts:
WindowChromePart::Root(the window, in the still form),Bar,Icon,Title,Balance(the room on the other side of a centred title),Line(the line under a bar with tabs),Controls,Minimize,Maximize,Close,MinimizeGlyph,MaximizeGlyph,CloseGlyph. The platform is the recipe’s variant (windows,macos,gnome,kde); statesWindowChromeState::Inactive,Maximized,Tabs. - To what reads the tree the bar is a
groupcalled by its label or its title, and each control abuttoncalled by its label. - The engine’s own title bar (
components::ChromeTitleBarwithcomponents::WindowControls) is drawn in the theme’s roles too:Mutedunder a line ofBorder, controls inForegroundonSecondaryHover, close onDestructive.
Window Tabs
Section titled “Window Tabs”The tabs of a desktop app’s title bar, as a browser or an editor has them: one is selected, the tab of what the window shows, and a person closes them, asks for a new one, and drags one along the bar or out of it.
use lurq::ui::{WindowTab, WindowTabs, icons};
// open: Signal<u32>, which file the window shows; files: the app's list of open files.WindowTabs::new(open, files.iter().map(|file| { WindowTab::new(file.id, &file.name).icon(icons::FILE_CODE).dirty(file.dirty)})).label("Open files").on_close(|id| close(*id)).on_add(|| open_new()).on_reorder(|from, to| move_file(from, to)).on_detach(|id| open_in_window(*id)).mount(ctx);
// The app holds which is selected, and is told the tab a person selects.WindowTabs::controlled(1, [(1, "blur.rs"), (2, "theme.rs")], |id| show(*id));| Builder | |
|---|---|
WindowTabs::new(Signal<T>, tabs), controlled(value, tabs, on_change) | The tabs, and which is selected: the one with the signal’s value, or the app’s value. T is the app’s own type; WindowTabs<T = ()> |
optional(Signal<Option<T>>, tabs), controlled_optional(value, tabs, on_change) | The same where the window may show none of its tabs (a start page): with None no tab is selected. A WindowTabs<Option<T>>, whose handlers are told &Option<T> |
tab(tab), tabs(tabs) | A tab, or tabs, after the others |
WindowTab::new(value, &str), (value, &str) | A tab of value with its label. The label takes the room the icon and the close slot leave and ends in an ellipsis where it does not fit |
WindowTab::icon(name), dirty(bool) | An icon before the label; a dot for changes that are not saved: in the close slot with the x in its place under the pointer, or after the label (dirty_mark) |
WindowTab::closable(bool) | Whether a person may close it: they may unless told otherwise. One that may not (a home tab) shows no close button, and nothing closes it: no middle press, no Delete, no Ctrl+W |
WindowTab::close_button(bool), on_close(Fn()) | Whether its close button shows (unless told otherwise; a closable tab without one is still closed by the middle button, Delete and Ctrl+W), and what hears it closed, before the strip’s on_close |
WindowTab::icon_only(bool) | Its icon alone, as a home tab: 28 wide, the icon in its middle, no label and no close slot. The label is still its name to tooling |
WindowTab::width(f32), max_width(f32) | A width of its own, which neither grows nor gives way; or the most it is wide, under the recipe’s most (a cap of the app’s on a long label, cut there with an ellipsis) |
WindowTab::fit_content(max) | As wide as what it shows, its icon, label, marks and close slot, up to max, where its label ends in an ellipsis: the app measures nothing. Never narrower than the recipe’s least width. In the list mode it keeps that width and leaves the strip whole; in the scroll mode it gives way to its least width, and the strip is reckoned with it at max. A width of its own wins, and a max_width caps it too |
WindowTab::trailing(element) | An element of the app’s after the label, in the tab’s Marks part, 6 after the label and 4 from the next: a count, a mark that something waits with its tooltip. It keeps its width, and the label gives way first |
WindowTab::list_label(&str), list_detail(&str), list_trailing(element) | Of the list of every tab (WindowTabsMenu::All): what the tab’s row says in place of its label (the page, where the tab says its project and its page), a quiet text after it that takes the room the label leaves (the project, part ItemDetail), both searched; and the app’s elements in the row after the mark of a tab not in the strip (part ItemMarks, 4 apart): a mark that something waits. They are elements of their own, apart from trailing, with ids of their own |
WindowTab::describe(name, value) | Says value of the tab under name to tooling (the DevTools, the MCP tree), before what the strip says of it, so a reader that takes the first value of a name takes the app’s: its route, its state. As Styled::describe of a component |
WindowTab::disabled(bool), id(..), key(..) | It cannot be selected, closed or dragged, and the keys pass it by. Its id, which its close button has with -close after it, and its parts after it: {id}-title, {id}-marks |
on_change(Fn(&T)) | Told the value of the tab a person selects (a press, a drag, the arrows, the window’s keys), after the signal is set: not a value the app sets, nor a press of the selected tab |
on_close(Fn(&T)) | Told the tab a person closes: its close button, a press of the middle button on it (any closable tab, whether its close button shows or not), Delete on it, or Ctrl+W (Cmd+W on macOS) on the selected one. The app removes it, and selects another where it was the selected one |
on_add(Fn()) | Told a press of the add button, which is shown once this is given |
on_reorder(Fn(usize, usize)) | Told a tab moved, from its place to the place it is to have: tabs.insert(to, tabs.remove(from)). Dragged along the strip, or Ctrl+Shift+PageDown and PageUp. The app reorders its list |
on_detach(Fn(&T)) | Told a tab dragged out of the strip and let go away from it. The app takes it out, to open it in a window of its own |
overflow(WindowTabsOverflow) | What the tabs do in less room than they need at their most: Scroll, the default, shares it down to their least width and then scrolls; List keeps their width, and the tabs that do not fit leave the strip, the last first and never the selected one, into the menu of the More button at the end of the tabs that stay. Mounted only: converted into an element on its own the strip cuts them at its end |
menu(WindowTabsMenu) | What the More button of the list mode opens: Hidden, the default, a menu of the tabs that left the strip; All, the list of every open tab (below) |
list_shortcut(bool) | Ctrl+Shift+A (Cmd+Shift+A on macOS) opens and closes the More button’s menu from anywhere in the window, apart from the window’s other shortcuts: off unless told. The menu of the hidden tabs opens only while a tab is hidden, the list of every tab at any time (under the tabs while none is hidden, see below). The More button’s tooltip says the keys |
menu_open(Signal<bool>), on_menu_open_change(Fn(bool)) | Whether the More button’s menu is open, as the app’s signal, which the strip sets and the app may set to open or close it; and what hears a person open or close it (the button, the shortcut, a choice, Escape, a press outside), not the app’s own changes |
list_clear_of(element), list_inset(f32) | The list of every tab stands 4 clear of the box of element (the title bar the strip is in) on the side it opens on, in place of the More button’s, lined up with the button along it; and stays list_inset inside the window’s edges (8 unless told), moved in from its end and never lower than that above its bottom, its rows scrolling |
more_tooltip(Fn(usize) -> String) | What the More button’s tooltip says for how many tabs left the strip, and what the button says of itself to tooling: “3 hidden tabs” in the locale’s words unless told |
dirty_mark(WindowTabsDirtyMark) | Where the dot of unsaved changes stands: InCloseSlot, the default, swapped for the x under the pointer; or AfterLabel, 6 after the label, the close button in its own slot drawn as a clean tab’s, both shown at once and nothing swapped |
tab_stop(bool) | Whether Tab stops in the strip; it does unless told otherwise. false is a strip the pointer and the app’s own shortcuts reach: Tab passes its tabs, its add button and its More button by, and a press of one leaves the focus where it was. A tab the app focuses still takes Left, Right and Delete, and the window’s keys work as before |
shortcuts(bool) | Whether the window’s keys work, from anywhere in the window: on unless told otherwise |
label(&str), add_label(&str), close_label(&str), more_label(&str) | What the list is called to tooling; the add button’s name (“New tab”); the word before a tab’s label that names its close button (“Close”, which makes “Close blur.rs”); what the More button and its menu are called (“Show the hidden tabs”) |
mount(ctx) | Mounted where it is declared: the dragged tab follows the pointer, the selected tab is kept in view where the strip scrolls, and the focus goes to the selected tab when the keys close the one it was on |
disabled(bool), state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. force draws the tab Tab stops on; id is the strip’s, with {id}-list for the list, {id}-add for the add button and {id}-more for the More button; a tab in its menu is the tab’s id with -item after it |
- The strip is as wide as its tabs and its add button, never wider, nor wider than what holds it, a row or a column. Given less room (a title bar narrower than its tabs), the tabs share it alike down to 72 each, the icon and the close slot, and past that the list scrolls sideways between the strip’s start and the add button, which stays at the end; mounted, the selected tab is kept in view. A wheel turned up and down over the strip scrolls it sideways, as a browser’s tab strip does.
- A press on a tab selects it when it is let go. A press and a move of more than 4 pixels is a drag: it selects the tab, and, mounted, the tab follows the pointer along the strip, drawn over the others, which make room for it where it would be let go. Let go,
on_reorder(from, to)is told where it went; let go more than the strip’s height above or below the strip, or out of the window past any of its edges (DragEvent::outside_window),on_detachis told instead; Escape puts the tab back, and its release tells nothing. Converted into an element on its own, the strip still tells where a dragged tab was let go, but the tab does not follow the pointer on the way. - A press on a tab, its close button or the add button goes no further than them (
stop_propagationonon_mouse_down), so a title bar that drags the window from a press is dragged from the strip’s empty room and the bar around it, and not from a tab. - With
overflow(WindowTabsOverflow::List)the tabs keep their width, and where the strip has too little room for them all, those that do not fit leave it whole with the line before them, the last first, never the selected one (the engine’sShrinkLimit::Dropanddrop_marker, learned before the frame is painted). The More button follows the tabs that stay, laid out only while a tab has left: how many left, 12, and a chevron of 12. Its menu lists them in their order with their icons; choosing one selects it, which brings it back into the strip in place of the last that fits, and gives it the focus. A drag moves a tab among those in the strip (on_reorderis told the places among them all), and the window’s keys go round every tab, those in the menu too, each selected coming back into the strip. - The tabs are one stop of Tab (focus groups), at the selected tab: Left and Right select the next tab and the one before in the strip, and Delete closes the focused one where it is closable, whether its close button shows or not. The More button and the add button are stops after them, Enter and Space open the More button’s menu with the focus on its first item, and Escape gives it back. A close button and a press of the middle button are for the pointer; the keyboard has Delete.
tab_stop(false)takes all of them out of the order of Tab. - The window’s keys are heard wherever the focus is: Ctrl+Tab and Ctrl+Shift+Tab select the next tab and the one before, round at the ends, as Ctrl+PageDown and Ctrl+PageUp do on Windows and Linux; Ctrl+W (Cmd+W on macOS) closes the selected tab; Ctrl+Shift+PageDown and PageUp move it on and back.
shortcuts(false)turns them all off. A key the strip takes is not passed on (prevent_default), and a key something took before it is not the strip’s: in a window whose page has document tabs with their keys on, a press switches the documents and not the window’s tabs, as in an editor. An app that wants the window’s tabs to have the keys turns the documents’ off (DocumentTabs::shortcuts(false)). - The gap of the
Listpart is the room between two tabs (and between a separator and the tabs beside it) and before the More button; the gap of theRootpart the room before the add button. The strip counts both as it fits its tabs: in the list mode a tab leaves with its gap and the separator before it, and comes back as soon as that room is there again. A separator stands between two tabs that are not the selected one whether they are in the strip or not, and in the list mode the separator before the add button keeps its room, drawn only after a tab that is not the selected one. A separator the recipe makes 0 wide is not laid out. The default recipe has no gap; Orchester’s has 2 and no separators (.base(WindowTabsPart::List, |s| s.gap(2.0)), the same forRoot, andSeparator0 wide). - The More button points its chevron up while its menu is open, and the strip is then in the state
MenuOpen, which the recipe draws as pressed. Its tooltip says how many tabs left (“8 hidden tabs”), with the keys of thelist_shortcutwhere it has one. - With
menu(WindowTabsMenu::All)the More button opens the list of every open tab, in the strip’s order, under it: a panel 320 wide with a search field at its head once it holds more than eight tabs (“Search 12 open tabs”), and a row of each tab whose label (or its row’slist_labelorlist_detail) holds what is typed, in any case, or “No open tab matches “…””. A row has the tab’s icon and label, an eye struck through where the tab is not in the strip, a check on the selected tab, and a close button whose x shows while the row is under the pointer or focused. The focus goes into the list as it opens, to the search field or else to the selected tab’s row, and back to the More button as it closes. Down goes from the search field to the first row and Up from the first row back to it; Up, Down, Home and End move through the rows; Enter and Space choose a row, as a press does, and Enter in the search field chooses the first that matches: the tab is selected and comes back into the strip, and the list closes. The middle button and Ctrl+W (Cmd+W on macOS) on a row close its tab, and the keys go on to the next row: while the list is open Ctrl+W is the row’s, never the selected tab’s. Escape empties the search field and then closes the list; a press outside closes it. While the list has the focus its keys are its own (keys_first): Ctrl+W (Cmd+W), Enter, Escape, the arrows and every key pressed without Ctrl, Alt or Cmd are not heard by the page under it, so a window’s own Ctrl+W does not close the selected tab as well and a dialog’s Enter under the list does not confirm it. While it is open, the row of the selected tab, or the first that matches the search, is scrolled into view, as it opens and as the search changes. The list stands 4 under the More button, or under whatlist_clear_ofnames, and 8 (list_inset) inside the window’s edges, never lower than that above its bottom; past that its rows scroll. It opens with no tab hidden too, by thelist_shortcutand bymenu_open: the More button stays hidden then, and the list hangs from the tabs, 4 under them (or under whatlist_clear_ofnames), its end at the end of the tabs; a press on a tab while it so hangs is not outside it. While it leads with its search field the strip is in the stateSearchable, and the rows under the field abut; without one they are 2 apart. Rows have the ids{id}-itemafter their tab’s id, their close buttons{id}-item-close, their marks{id}-item-hiddenand{id}-item-current; the panel is{strip}-paneland the field{strip}-search. To what reads the tree the panel is adialogand the rows alistboxofoptions called “Open tabs”, eacha11y_selectedwhere it is the selected tab, and described “Not in the tab strip” where it is not in the strip. - Parts:
WindowTabsPart::Root(the strip),List,Tab,Icon,Title(the label with what stands right after it),Label,Marks(the app’s elements after the label),Close(the slot at a tab’s end, its close button),CloseIcon,Dot,Separator,Add,AddIcon,More(the button of the tabs that left the strip),MoreLabel,MoreIcon, and of the list of every tabPanel,Search,Items,Item(a row, in the states of its tab),ItemIcon,ItemLabel,ItemDetail(the quiet text after the label),ItemHidden,ItemMarks(the app’s elements),ItemCurrent,ItemClose,ItemCloseIconandEmpty. States:WindowTabsState::Selected,Dirty,Dragged,DisabledandIconOnlyof a tab, andDisabled,Overflowing(some tabs are in the More button’s menu),MenuOpen(its menu is open) andSearchable(the list of every tab leads with its search field) of the strip. With the dot after the label, the dot and the close slot are drawn in the recipe of a clean tab, so that the pointer swaps nothing; the tab and its label are stillDirty. - In the design the strip is 32 high with its tabs abutting. A tab is 128 by 32, round by 8 at its top corners and square at its bottom, padded 10 at its start and 6 at its end, its parts 8 apart: an icon of 14, the label 12 in the regular weight, and a close slot of 18 round by the small radius with an x of 12 in
MutedForeground. The selected tab isBackground, the color of the content it joins in a title bar, edged at its top and sides by a line of 1 inBorder(on the light palette’s white bar its fill alone does not tell it apart), its icon and labelForeground; another has no fill, its icon and labelMutedForegroundand its x at 0.6, and under the pointerSecondaryHoverwith its x whole. The dot is 7 inForeground. A separator is 1 by 16 inBorder, between two tabs that are not the selected one and before the add button. The add button is 30 by 28, round by the small radius, with a plus of 14 inForeground. Where the board is silent: the close slot under the pointer isMutedand the add buttonSecondaryHover, the ring of the focus is inside a tab, and a disabled tab is dimmed. A tab of its icon alone is 28 wide with no padding. The dot after a label and the app’s marks are 6 from the label, the marks 4 apart. The More button is 28 high, padded 8 across, its count 12 and its chevron 12 4 apart inMutedForeground,ForegroundonSecondaryHoverunder the pointer, its ring inside it. A tab with a cap or a width of its own grows to its most as the others do, by as much as it can grow, so that every tab is at its most when the strip has room for all of them so. - In a title bar the strip sits on the bar’s bottom edge, and the bar has no line under it, so the selected tab runs into the content.
- To what reads the tree the list is a
tablistwith the strip’slabel, each tab atabwitha11y_selected, after what the app said of it withdescribe, and its close button is named byclose_labeland the tab’s label. In the list mode each tab says where it is among them all (a11y_posinset,a11y_setsize), and the More button is named bymore_label, described by how many it holds (“3 hidden tabs”, in the locale’snavigation.hidden_tabs, or whatmore_tooltipsays), and saysa11y_haspopupanda11y_expanded. - A renderer that draws other window tabs is given the view:
view.part(..),view.tab_part(index, ..),view.tab(index),view.close(index),view.separator(),view.add(),view.more(),view.list(),view.hiddenandview.hidden_count(), andview.render()the default.
Command Bar
Section titled “Command Bar”The tabs of a window’s commands over the commands of the selected one, in groups with a label under each: the ribbon of an editor or a file manager. It is a Tabs over a Toolbar: the groups, the overflow, the focus group and the menu are the toolbar’s.
use lurq::ui::{CommandBar, CommandBarCommand, CommandBarTab, Toggle, ToolbarCommand, ToolbarGroup, ToolbarItem, icons};
let clipboard = ToolbarGroup::new() .label("Clipboard") .item(CommandBarCommand::new("Paste").icon(icons::PASTE).large(true).on_select(paste)) .item(ToolbarItem::stack([ CommandBarCommand::new("Cut").icon(icons::CUT).on_select(cut), CommandBarCommand::new("Copy").icon(icons::COPY).on_select(copy), ]));let format = ToolbarGroup::new() .label("Format") .item(ToolbarItem::from(Toggle::new("Bold").icon(icons::BOLD).icon_only(true).on(bold.get())).shortcut("Ctrl+B"));let insert = ToolbarGroup::new() .label("Insert") .item(CommandBarCommand::new("Table").icon(icons::TABLE).large(true).on(table.get()).on_change(set_table));
CommandBar::new(tab.clone(), [ CommandBarTab::new("home", "Home") .item(clipboard) .item(format) .item(insert) .secondary_command(ToolbarCommand::new("Customize").on_select(customize)), CommandBarTab::new("view", "View").item(view),]).mount(ctx);| Builder | |
|---|---|
CommandBar::new(Signal<T>, tabs), controlled(value, tabs, on_change) | A bar whose selected tab is the signal’s value, or the app’s value, told the value of each other tab a person selects. CommandBar<T = ()> is generic over the tabs’ values |
on_change(handler) | Called with the value of a tab a person selects, after the signal is set. Each one adds |
CommandBarTab::new(value, label) | A tab, with item(impl Into<ToolbarItem>) and items(..): what its bar holds while it is selected, as a toolbar has it (labelled ToolbarGroups, ToolbarItem::stack, commands, toggles, a select), disabled, id and key |
CommandBarTab::secondary_command(ToolbarCommand), secondary_commands(..) | A command that is never in the bar, only in the menu behind the chevron, after what did not fit; with one the chevron is always there |
label(&str) | What the bar is called to what reads the tree: “Commands”. The row of its commands is called by the selected tab |
more_label(&str) | What the chevron at the end is called, in its tooltip and to what reads the tree: “More commands” |
disabled(bool) | Its tabs and its commands take no input, the items of its menu too. State: CommandBarState::Disabled |
mount(ctx) | Puts the bar in the tree of ctx’s component: its tabs and its toolbar keep what they keep. build(theme) and From<CommandBar> for Element draw it once with nothing kept: what does not fit is cut off |
state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. force draws the chevron; a command is forced with its own. The tabs have the id with -tabs after it, the row of commands -bar, the chevron -bar-more and its menu -bar-menu |
CommandBarCommand | |
|---|---|
new(&str), icon(name) | A command: its icon and its label, 24 high |
large(bool) | Its icon of 20 over its label of 11, 56 by 52: what a person reaches for first in a group. State: CommandBarCommandState::Large |
on(bool), on_change(Fn(bool)) | It is a toggle, picked out while on, and a press tells on_change the other value. State: On |
on_select(handler) | What running it does: a press, Enter or Space, or its item in the menu. Each one adds |
disabled(bool), state, style, rules, force, id, key | As a button has them; its item in the menu has the id with -item after it |
- What a command bar is that a toolbar is not, as the board draws it: tabs over the commands, each tab a set of its own; groups with a label under each and a line at the end of each, where a toolbar has lines between groups; large commands, the icon over the label, beside stacks of two small ones; and the overflow behind a chevron at the end, a group whole under its label. All of that but the tabs is the toolbar’s:
ToolbarItem::stack, a labelledToolbarGroup,Toolbar::more_iconandToolbar::secondary_command. - Tab stops in the tabs once and in the commands once. Left and Right select the next tab and move between the commands; a disabled one is passed by. What does not fit goes into the menu the last first, a labelled group whole under its label and a toggle checked; a stack goes whole.
- Parts:
CommandBarPart::Root,Tabs,Tab,TabLabel(laid over the tabs’ list, tab and label),Bar(laid over the toolbar’s root),More(laid over the toolbar’s More button);CommandBarCommandPart::Root,Body,Icon,Label. A command’s states:CommandBarCommandState::Large,On,Disabled. - In the design the bar is a frame of the background’s color with an edge of 1 and the large radius. The tabs are a row 32 high on
Barover a line of 1, padded 8, 2 apart; a tab is padded 12, its label 13 in the muted foreground, the selected one 600 in the foreground and underlined with 2. The commands are padded 8 and 4; a group is padded 10, its commands 4 apart, its label of 10 in the muted foreground 4 under them, and a line of 1 at its end but the last’s. A small command is 24 high, padded 8, its icon of 14 and its label of 12 6 apart; a large one 56 by 52, its icon of 20 over its label of 11; a toggle of its icon alone is 28. At the far end the chevron is 28 by 52, level with the large commands. Under the pointer and while on a command has the fill of what is picked out. - To what reads the tree it is a
groupcalled by its label, which holds atablistand atoolbarcalled by the selected tab; a toggled command saysa11y_pressed. - A renderer that draws another bar gets a
CommandBarView: itstabsand itsbar, built.
In a narrow room. The bar’s groups go behind its chevron, the last first, as a toolbar’s controls do; its tabs, mounted with it, scroll between their buttons when they have no room; and a bar narrower than what stays in it scrolls sideways.
Find Bar
Section titled “Find Bar”The search of what a view shows, hung from the top of the view over its content: the field, the count, the next and the previous match, the options of the search, and a row that replaces.
use lurq::{components::Stack, ui::FindBar};
Stack::new() .child(editor) .child( FindBar::new(query.clone()) .open(find_open.clone()) .matches(current, total) .match_case(case.clone()) .whole_word(whole.clone()) .regex(regex.clone()) .replace(with.clone()) .replace_open(replacing.clone()) .on_query(move |text| search(text)) .on_next(next) .on_previous(previous) .on_replace(move |text| replace_current(text)) .on_replace_all(move |text| replace_every(text)) .return_focus(editor_ref.clone()) .mount(ctx), );
// Ctrl+F is the app's to bind: a key handler over the view opens the bar.view.on_key_down(move |event: KeyboardEvent| { if event.ctrl && event.key.eq_ignore_ascii_case("f") { event.prevent_default(); find_open.set(true); }});| Builder | |
|---|---|
FindBar::new(Signal<String>) | The bar of what is typed in the signal: the app finds it and gives the bar the count |
on_query(handler) | Called after each edit of the field, with what it holds |
on_next(handler), on_previous(handler) | Going to the next match and the one before: Enter and Shift+Enter in the field, F3 and Shift+F3 in the bar, the arrow buttons |
matches(current, total) | The current match, from 1 (0 where none is), and how many there are: “3 of 12”, “No results” for none. Without it the bar says nothing of the count |
count_text(Fn(usize, usize) -> String) | What it says of the count in place of “3 of 12” |
match_case(Signal<bool>), whole_word(..), regex(..) | An option of the search in the field, “Aa”, “ab” and ”.*”, shown where it is given. Each has _controlled(on, on_change) and on_<option>_change(handler), as a second value of a component has them |
replace(Signal<String>) | What the matches are replaced with: the replace row under the field, with its buttons |
replace_open(Signal<bool>) | Whether the replace row is shown: the chevron before the field shows it and hides it. Without it the row is always there |
on_replace(handler), on_replace_all(handler) | Told the replace text: its buttons, and Enter in the replace field for the current one |
open(Signal<bool>) | Whether the bar is shown: Escape and the close button set it to false. Without it the bar is always there |
on_dismiss(handler), on_open_change(handler) | Called when a person closes it, after the signal is set |
return_focus(ElementRef) | Where the focus goes as the bar closes with the focus in it: the view it searched |
mount(ctx) | Puts the bar in the tree of ctx’s component, which puts the focus in its field as it opens (as its open signal turns true, or as it is first rendered where it has none: a bar open from the start leaves the focus where it is) and where return_focus says as it closes. build(theme) and From<FindBar> for Element draw it with nothing kept |
disabled(bool) | Its controls take no input. State: FindBarState::Disabled |
label, placeholder, replace_placeholder | What the bar and its field are called, “Find”, and what the fields show: “Find”, “Replace” |
previous_label, next_label, close_label, match_case_label, whole_word_label, regex_label, replace_label, replace_all_label, toggle_replace_label | What its controls are called to what reads the tree |
match_case_text, whole_word_text, regex_text | What its options show: “Aa”, “ab” and ”.*“ |
state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. force draws its buttons. Its field has the id with -field after it; its buttons -previous, -next, -close, -toggle-replace, -replace, -replace-all; its options -match-case, -whole-word, -regex; the replace field -replace-field |
- It is as large as the room it is given and takes no press itself: put it over the view it searches, in a
Stack. The bar hangs 8 from the top and the end of that room, 440 wide or as wide as the room, comes down into place as it opens and goes back up as it closes. - The keys act where the focus is in the bar: Enter, Shift+Enter, F3, Shift+F3, Escape. The app binds what opens it (Ctrl+F) and F3 elsewhere.
- Parts:
FindBarPart::Root,Bar,FindRow,ReplaceRow,Field(laid over an input’s box),Options,Option,OptionOn,Count,Button,ButtonIcon(laid over a button’s root and icon),Pad. States:FindBarState::Closed,NoMatches,Expandable,Replacing,Disabled. - In the design the bar is of the popover’s color with an edge of 1, the large radius and the large shadow, padded 6, its rows 6 apart and their controls 4 apart. The field is an input 28 high with its text of 13, padded 8 before it and 3 after the options, which are 22 square with a glyph of 11 in the muted foreground; one that is on has the fill of what is picked out, an edge in an input’s color and its glyph in the foreground. The count is 11 in the muted foreground, padded 6, in the destructive color where nothing matches. The buttons are ghost ones 24 square with icons of 14. The replace row is indented 28 under a bar that has the chevron and ends 52 before the end.
- To what reads the tree it is a
searchcalled by its label; each option saysa11y_pressed, the chevrona11y_expanded, and the count isa11y_livepolite. - The bar counts and the app finds: what it finds it marks on its text with a Highlight that keeps the text’s weight, every match and the current one stronger, which brings the current one into view as it changes.
find_matches(text, query, FindOptions)finds the ranges of a query under the bar’s three options, for an app that searches a plain text. - A renderer that draws another bar gets a
FindBarView:field(),options(),count(),find_row(),replace_row(),bar(), andbutton(..)for a button of its own.
In a narrow room. A mounted bar measures its field: where the field has no room for the options in it,
they go behind one button (options_label, “Search options”) whose menu checks the ones that are on; the count
and the arrows stay. Under the least a field is wide, the count and the buttons go on to a line under it. The board draws the bar at 440 with the options in its field and no narrower form: the one button is lurq’s.
Text Editing
Section titled “Text Editing”What every field of the design system draws while it is typed in. It is the engine’s text input, so nothing is asked for but the two marks an app gives a field: the ranges its spelling checker found, and what would complete what is typed.
use lurq::ui::{ContextMenu, Input, MenuItem, Textarea};
// The app's own checker says which bytes of the text are wrong.Input::new(text.clone()).squiggles(misspelled(&text.get()));Textarea::new(note.clone()).squiggles(misspelled(¬e.get()));
// What would complete what is typed, for what the field holds now. Tab takes it.Input::new(command.clone()).completion("n --release");
// The commands of an edit in one row over the field.ContextMenu::new(open.clone(), Input::new(text.clone())) .bar(true) .items(["Cut", "Copy", "Paste", "Select All"].map(|name| MenuItem::new(name)));| Mark | What draws it | |
|---|---|---|
| Selection | The engine, in PaletteColor::Selection | Behind the band of the selected text (the font’s ascent and descent), while the field has the focus. TextInput::selection_color for one field |
| Caret | The engine, in the color of the text | A line where the next character goes, as wide and as high as the theme’s caret says: the board’s 1.5 by 18 in type of 14. It blinks unless the theme’s CaretMode is Persistent. TextInput::caret_color for one field |
| Composition | The engine, in the color of the text | A line under what an input method is composing, until it is committed, as thick as the theme’s caret says: the board’s 1.5 |
| Spell check | Input::squiggles(ranges), Textarea::squiggles(ranges) | A wavy line in Destructive under each range, bytes of the text, on every row the range is on. lurq has no checker: the app finds the ranges, and again after an edit. The part Squiggle (InputPart, TextareaPart) gives them another color |
| Ghost completion | Input::completion(&str) | What would complete what is typed, drawn after it in MutedForeground at 0.7 while the field has the focus, holds text, and has the caret at its end with nothing selected. Tab puts it in the field as an edit (through on_input, one step of the undo) and the focus stays; anywhere else Tab goes on. The part InputPart::Completion gives it another color and opacity |
| Edit menu | ContextMenu::bar(true) | The commands of selected text in one row over a field |
- On the engine’s input the two marks are
TextInput::squiggles(InputSquiggles::new(ranges).color(..))andTextInput::ghost(InputGhost::new(text).color(..).opacity(..)). A masked input draws no squiggle, and an input with tokens or styled spans no ghost. - The key that takes a completion is not drawn by the input: put a
Kbdbeside the field where it should be said. - The board fills a selection with
info-muted; the engine’s is the theme’sSelectionrole, which the board has as a variable of its own.
Tray Popover
Section titled “Tray Popover”The small panel a press of an app’s icon in the system tray or the menu bar opens: who the app is and how it is doing, a few switches, a few commands.
use lurq::ui::{TrayAction, TrayPopover, TrayStatusVariant, TrayToggle, icons};
// sync, paused: Signal<bool>, kept by the app.TrayPopover::new("lurq") .icon(icons::BOX) .status("Synced just now") .item(TrayToggle::new("Sync in background").bind(sync.clone())) .item(TrayToggle::new("Pause notifications").bind(paused.clone())) .separator() .item(TrayAction::new("Open lurq").on_select(move || show_window())) .item(TrayAction::new("Preferences…").on_select(move || preferences())) .item(TrayAction::new("Quit").on_select(move || quit()));
// Over the app's own window, beside an element of its own: open: Signal<bool>, anchor: ElementRef.TrayPopover::new("lurq") .status("Offline") .status_variant(TrayStatusVariant::Warning) .item(TrayAction::new("Retry now").on_select(move || retry())) .anchored(open.clone(), anchor.clone());| Builder | |
|---|---|
TrayPopover::new(&str) | What the app is called: the title, and what the panel is called |
icon(impl Into<Name>), media(element) | The app’s mark before its title: an icon of 16 on a tile of 28 in the primary color, or the app’s own picture in place of the tile |
status(&str), status_variant(impl Into<Name>) | How the app is doing, under its title after a dot, and the tone that colors the dot: a TrayStatusVariant, Neutral, Info, Success (the default), Warning, Destructive |
item(impl Into<TrayItem>), items(..) | A row: a TrayAction or a TrayToggle |
separator() | A line between two groups of rows. The line under the header is there by itself |
child(element), children(..) | Something of the app’s own among the rows: a progress, an account |
anchored(open, anchor) | Shows the panel over the window beside anchor while the Signal<bool> is true, in place of where it is declared |
placement(Placement), offset(..), collision(CollisionStrategy) | Where an anchored one stands: under its anchor with its end at the anchor’s end (BottomEnd; TopEnd over a taskbar), 6 from it, to the other side then into the window where there is no room |
on_dismiss(Fn()), dismiss_on_escape(bool), dismiss_on_outside_press(bool) | What is told after Escape or a press outside closed an anchored one, and whether each closes it: both by default. A command is no dismissal |
width(..), label(&str), state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a popover has them. force draws its first command’s states |
| Row | |
|---|---|
TrayAction::new(&str) | A row that runs a command: on_select(Fn()), disabled(bool), id, key |
TrayToggle::new(&str) | A row with a switch at its end: bind(Signal<bool>), or on(bool) with on_change(Fn(bool)) told what a press asks for; disabled(bool), id (the switch’s), key |
- Declared plainly it is the panel in the flow, 280 wide at most. lurq has no tray icon: the icon and its press are the platform’s, or a crate’s for it (
tray-icon). An app that has one opens a window with no frame on the press,ctx.window_opener().open_with(WindowOptions::new("lurq", 280, 272).undecorated(), ..), mounts a root that renders the panel, and closes the window (WindowHandle::close) from its commands. What lurq does not have yet for that window is a place on the screen, a level over other windows and a way out of the taskbar: until then the window opens where the system puts it. anchoredshows it as a popover is shown, for a status item of the app’s own title bar or status bar: Escape and a press outside close it, the focus goes into it as it opens and back as it closes, and a command closes it first and then runs, so what the command opens keeps the focus it takes.- A press of a toggle’s row turns its switch as a press of the switch does. Bound, the signal is set and then
on_changeis told; not bound,on_changeis told the value a press asks for and the row stays as the app holds it. Nothing is told when the app sets the signal. - Every command and every switch is a stop of Tab, and the arrow keys move through them, past the lines. A command is pressed by Enter and Space and has the ring inside it; a row that is
disabledis faded, takes no press and is passed by. - A title, a status and a row’s words longer than their room are cut with an ellipsis; a switch keeps its room. Rows follow the theme’s density: a command is 28 at the default, 20 compact, 36 comfortable and 40 under a finger, and a toggle’s row 2 more.
- To what reads the tree it is a
group(adialogwhere it is anchored) called by its label or its title; its status is astatus, a command amenuitem, and a toggle its switch. - Parts:
TrayPopoverPart::Panel,Header,Media(the tile),Icon,Text,Title,Status,StatusDot,Description(the status’s words),SeparatorandLine,ToggleandToggleLabel,Item(a command),Body(what the app puts among the rows). Variants byTrayStatusVariant. States:TrayPopoverState::Disabled, resolved on a row’s parts. - In the design the panel is 280 wide on
Popoverin an edge of 1 inBorder, 12 round, with theLgshadow, padded 10, what it holds 8 apart. The header is 4 from the sides: the mark of 16 inPrimaryForegroundon a tile of 28 inPrimary,Mdround, 10 before the title (13, semibold) over the status 1 under it, a dot of 6 inSuccess5 before words of 11 inMutedForeground. A line of 1 inBorderhas 4 over and under it. A toggle’s row is 30 and a command 28, both 4 from their sides with words of 13; the command under the pointer is inHighlight,Smround. The board draws the tray the popover hangs from, which is the platform’s, and no focused or disabled row.
Path Field
Section titled “Path Field”The path of a folder or a file in an input, with a button beside it that browses for one: where a project is kept, the file a report is written to.
use lurq::{files::FileDialog, ui::{PathField, PathKind}};
// path: Signal<String>. The app answers the button: it opens what it likes and sets the signal.PathField::new(path.clone()).on_browse(move || choose_a_folder(&path));
// Told what its path is of and mounted, the button opens the system's dialog and sets what is chosen.PathField::new(folder.clone()) .picks(PathKind::Folder) .dialog(FileDialog::new().title("Project folder")) .on_pick(|path| open_project(path)) .mount(ctx);
PathField::new(report.clone()) .picks(PathKind::SaveFile) .browse_label("Save as…") .dialog(FileDialog::new().filter("Markdown", &["md"]).file_name("report.md")) .mount(ctx);| Builder | |
|---|---|
PathField::new(Signal<String>) | A field bound to the path: it shows what the signal holds, and what is typed or chosen is set on it |
on_browse(Fn()) | Called on a press of the button, before the system’s dialog opens where the field opens one. A second one is called after the first |
picks(PathKind) | What the path is of: PathKind::Folder, File (one that is there, to open) or SaveFile. Mounted, the button then opens the system’s dialog for it and sets the path chosen; of what is dropped on the field, a folder or a file of that kind is taken. Without it the button only tells on_browse, and a drop is taken whatever it is |
dialog(FileDialog) | The dialog as the button opens it: its title, the kinds of file it shows, the name a file to save starts with. It opens where the field’s path is (in the folder itself for a folder, in the file’s folder for a file) unless it is given a folder of its own |
on_pick(Fn(&str)) | Called with the path a person chose in the dialog or dropped on the field, once the signal is set. Not for what is typed (on_input), nor for what the app sets |
mount(ctx) | Puts it where it goes, keeping the dialog it opens: a second press while the dialog is open opens no second one. build(theme) and From<PathField> for Element are its still form, whose button tells on_browse and opens nothing |
browse_label(&str) | What the button says, and is called to what reads the tree: “Browse…” unless told otherwise |
icon(..) | The glyph at the start of the box, by its name in the theme’s set: a folder, or a file for a field that picks one, unless told otherwise. icon(None) takes it away |
placeholder(&str), size(..), invalid, warning, valid, read_only, disabled, full_width, label(&str), name(..), on_input(..), on_submit(..) | As an input has them. PathFieldSize is the input’s sizes, the button’s too, and the small one unless told: the board’s. A read-only field’s button takes nothing; full_width is in place of 440 |
state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. id is the id of the control, what is typed in; the button has it with -browse after it |
- It is an input and an outlined button side by side: Tab stops in the input, then on the button; Enter in the input is told to
on_submit, Enter and Space on the button press it. - The dialog is the system’s with the feature
file_dialog, throughlurq::files::FileDialog(pick_folder,pick,pick_save): see Files a person gives for what each platform has. A browser has no dialog for a folder or for where to save, and no path of a file: there the button tellson_browseand nothing is chosen. Under an MCP server with aFileDialogBrokerthe broker answers in the dialog’s place. - A folder or a file dragged from the system and dropped on the field is its path, as one chosen in the dialog is: set on the signal, then told to
on_pick. A field that is disabled or read only takes none. - In a field it is called by the field’s label and judged as the field is:
Field::new("Output folder", PathField::new(path)), mounted by a field that is mounted. - Parts:
PathFieldPart::Root(the two side by side),Field(laid over the input’s root),Control(over the input’s box: the type of the path),Icon(over the input’s icon),Button(over the button’s root). States:PathFieldState::Invalid,Warning,Valid,ReadOnly,Disabled,FullWidth. - In the design (
Path Field) it is 440 wide, the input and the button 8 apart and 32 high. The path is in the mono type at 12 inForeground, 10 from the edge of the box, after a folder of 16 inMutedForegroundand 8; the button is outlined, 12 in from its sides. A medium field is 36 with a path of 13, a large one 40 with a path of 14. A path longer than the box scrolls in it as in any input, and the button keeps its room. - To what reads the tree the input is a
textboxcalled by its label, and the button abuttoncalled by what it says. - A renderer that draws another path field (
PathFieldRenderer) is givenview.input(the input’s own view),view.field()(the input in its place, which takes a drop),view.button(),view.root()andview.browse()(what a press of the button does).
Settings Card
Section titled “Settings Card”A card of a settings page: one setting with its icon, its title, its description and the control that sets it, which may open to more settings; or the rows of several settings in one card.
use lurq::ui::{Button, ButtonVariant, ListItem, Select, SelectSize, SettingsCard, Switch, icons};
// One setting in a card of its own. With rows it opens to them; mounted, it keeps whether it is open.SettingsCard::new( ListItem::new("App theme") .icon(icons::PALETTE) .description("Choose how lurq looks.") .trailing(Select::new(theme, themes).size(SelectSize::Sm)),).item(ListItem::new("High contrast").trailing(Switch::new("High contrast").label_hidden(true).bind(contrast))).item(ListItem::new("Accent color").value("Blue").chevron(true).href("/settings/accent")).mount(ctx);
// Several settings in one card, a row each.SettingsCard::group([ ListItem::new("Open at login") .description("Start lurq when you sign in to this computer.") .trailing(Switch::new("Open at login").label_hidden(true).bind(login)), ListItem::new("Default project folder") .description("Where new projects are created.") .trailing(Button::new("Choose…").variant(ButtonVariant::Outline).size("sm")),]).label("Startup");| Builder | |
|---|---|
SettingsCard::new(ListItem) | The card of one setting: the row is its own, with its icon, its title, its description and the control that sets it at its end |
SettingsCard::group(rows) | A card of several settings, a row each, with a line between each two |
item(ListItem), items(rows) | Rows, after those it holds: the settings of a group, or what the card of one setting opens to |
open(bool) | Whether the rows under the card’s own row are shown, where the app holds it: the card opens nothing itself, and tells on_open_change |
bind(Signal<bool>) | Open while the signal is true, which a press of the card’s row turns; the handlers of on_open_change are told after it is set |
default_open(bool) | Whether a card that keeps it itself starts open |
on_open_change(Fn(bool)) | Called on a press of the card’s own row with what the card is to be: open if it was closed. Not for what the app sets. A second one is called after the first |
mount(ctx) | Puts it where it goes, keeping whether it is open where the app says neither open nor bind. Built on its own (build, .into()) with neither, it is its still form, as it starts |
label(&str) | What the card is called to what reads the tree, in place of the title of its own row. It draws nothing: a heading over a group of settings is the page’s own text |
density(Density), width(..) | How high its rows are, whatever the theme is at; a width of its own in place of all the room it is given |
disabled(bool), state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. disabled takes everything in the card out of input and dims it; force draws the card’s own row where it opens, and the pressed rows of a group. A row has the id the app gave it |
- A row is a list item: its
icon, itsdescription, the control at its end (trailing), avalueand achevronfor one that leads to a page of its own, whichon_clickorhrefmakes pressed. The card puts each in the list item’sSettingstate, which is the design’s Settings Row. Nothing else is a settings row:ListItem::new("Open at login").description("..").trailing(Switch::new(..))in aSettingsCard. - A card with a row of its own and rows under it opens. Its own row is pressed as a whole, by the pointer and by Enter and Space, after what the app made of its press, and shows a chevron at its end: down while the card is closed, up while it is open. A press of the control in that row is the control’s and not the card’s, and the control is a stop of Tab after the row. The rows open and close with their height over the theme’s base duration and fade with it, as a collapsible’s panel does, and at once where motion is reduced; while the card is closed they are not there.
- In a card the rows that are pressed and the controls in rows are one group to Up and Down, Home and End, as in a list.
- Parts:
SettingsCardPart::Root(the card),Header(laid over the root of the card’s own row: the room over and under it),Panel(what opens and closes),Body(what the panel holds, under a line). States:SettingsCardState::Open,Disabled,Header(it has a row of its own). A row’s parts are the list item’s. - In the design (
Settings Card,Settings Rowand the cards of the Preferences window) the card is onCardwith an edge of 1 inBorderand the large radius, as wide as its room. A setting is 14 in from its sides, 12 between what it holds: an icon of 20 inForeground, the title 13 at 500 over the description, 12 inMutedForeground, 2 under it, the control, and a chevron of 16 inMutedForeground12 after it. The card’s own row is 14 from the top and the bottom of the card, 61 high with a description; a row of a group is 12 from them, 57 high, with a line of 1 inBorderbetween each two, along the bottom of the row over it. The board draws no setting of one line and no open card: a setting of one line is 44 at the least, and the rows of an open card are under a line. A longer title is cut with an ellipsis, a longer description wraps, and the control keeps its room. In a room that leaves the title and the description less than 80 beside the control (a card in a window as narrow as a phone), the control and the chevron go under the text, at the row’s start, and the description is not broken in its words; a wide room never reaches it. - A setting follows the density by half of a row’s step over and under it: a row of a group with a description is 49, 65 and 69 at compact, comfortable and touch, and one of a single line 36, 52 and 56.
- To what reads the tree (
lurq_snapshotof the MCP server) the card is agroupcalled by its label or the title of its own row, its rows alist; the row of a card that opens is abuttonwitha11y_expanded. - A renderer that draws another card (
SettingsCardRenderer) starts fromview.root()and puts in itview.header()(the card’s own row with its behavior),view.panel()(what opens and closes, with the rows while the card is open) orview.rows()(the rows of a group).
Column View
Section titled “Column View”A hierarchy as columns side by side: choosing an item of one shows what it holds in the next, as a file browser’s columns do.
use lurq::ui::{ColumnView, TreeItem};
// path: Signal<Vec<&str>>, the values from the top down to the item chosen last.ColumnView::new(path, [ TreeItem::folder("crates", "crates").items([ TreeItem::folder("lurq", "lurq").items([ TreeItem::folder("src", "src"), TreeItem::file("Cargo.toml", "Cargo.toml"), ]), ]), TreeItem::folder("docs", "docs"),]).label("Files").on_activate(|file| open_file(file)).mount(ctx);
// The path held by the app, which is told each new one.ColumnView::controlled(app.path(), items, |path| app.go(path));| Builder | |
|---|---|
new(path, items) | What is at the top, each a TreeItem<T> with what it holds (a tree view’s items), and the path chosen, bound to a Signal<Vec<T>>: the values from an item at the top down to the item chosen last |
controlled(path, items, on_change) | The path held by the app, which is told on_change(&[T]) and shows what it gives back |
on_change(handler) | Told the whole new path after a press or a key changes it, after the signal is set; not for the path chosen already, nor when the app sets it |
on_activate(handler) | Told of the item a double press or Enter activates: open the file |
press_activates(bool), activate_branches(bool), open_on_hover(bool) | For a menu of columns, a cascader’s: a single press activates the item it chooses; an item that holds others is not activated, and Enter goes into it as Right does (activate_branches(false)); the pointer on an item that holds others chooses it, opening its column |
label(&str), loading_label(&str) | What the view is called to what reads the tree, and the spinner of a column whose items are on their way, “Loading” |
disabled(bool), state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. id is the root’s, and each column has it with -column- and its place; force draws the item Tab stops on so |
mount(ctx) | In place of converting it: the view keeps where its columns are scrolled to, starts at the end of its path and brings the last column into sight as the path grows |
- The first column is what is at the top; each one after it is what the item chosen in the one before holds. A press of an item ends the path at it. An item on the path is in the highlight and the one the path ends at on the info fill; a value of the path that is no item ends the path before it.
- A
TreeItemmarkedlazywith no items yet has a chevron and, chosen, a column with a spinner: the app hears the path inon_changeand gives the item its children.iconandopen_icon(while the item is on the path),trailing,trailing_on_hoveranddisabledare a tree’s. - The view is one stop of Tab, at the item the path ends at, or the first. The choice follows the focus. Up and Down go through the items of a column, Home and End to its first and its last, without going round and without leaving the column; Right goes into what the item holds, to its first item, and Left back to the item the column is of, where the path then ends. A letter goes to the next item that starts with it, in the column and then in those after it. Enter activates. A disabled item is passed by.
- The columns share the view’s width, none narrower than the
Columnpart’s least width (160), and scroll sideways where they do not fit. A column scrolls down where its items are more than the view is high. The keys keep the item they go to in sight. - The keys are the engine’s: the view is a focus group that is
one_stop,activates, withtypeaheadand withoutwrap, and each item takes the arrows to the item they go to by its key (KeyboardEvent::focus_key), which may be in a column the choice has only just shown. - To what reads the tree it is a
groupcalled by its label, each column alistboxcalled by the item it is of, each item anoptionwitha11y_selected,a11y_level(its column),a11y_posinset,a11y_setsizeand, where it holds others,a11y_expanded. - Parts:
ColumnViewPart::Root,Column,Item,Icon,Label,Trailing,Reveal(around what is at the end of an item marked to show it on hover),Chevron,StatusandSpinner(of a column whose items are on their way). States:ColumnViewState::Selected(on the path),Current(the end of the path),Last(of a column: the last has no line at its end),Disabled. - In the design the view is 520 by 176 on
Backgroundin an edge of 1 inBorder,radius-lg. A column is padded 4 with a line of 1 inBorderat its end, its items 1 apart. An item is 26 high withradius-sm, 6 at each side, and holds an icon of 14 and a chevron of 12 inMutedForegroundand its label in the body’s type at 13, 6 apart. On the path it is onHighlight; at its end onInfo, its icon, label and chevron in white. Under the pointer and held down it has theStateHoverandStatePressedveils, the focus is a ring of 2 inRinginside it, and a disabled item is half opaque. An item follows the density: 18, 26, 34 and 38 high. - A theme’s renderer is given
ColumnViewView:view.columns(each aColumnViewColumnwith itsitems, each aColumnViewItemwith its label, icon, whether it opens, is selected, is current, is disabled),view.root(),column.render(), and on an itemitem.button(),item.icon(),item.label(),item.chevron()anditem.render().
Sortable List
Section titled “Sortable List”A list whose rows a person puts in another order, by a drag of a row or of its handle and by the keys: the columns of a table, the layers of a scene, the steps of a pipeline.
use lurq::ui::{SortableItem, SortableList, move_rows};
// sections: Signal<Vec<&str>>, the rows in the app's order.let order = sections.clone();SortableList::new(sections.get().into_iter().map(|name| (name, name))) .label("Sections") .on_reorder(move |from, to| { order.update(|rows| { let row = rows.remove(from); rows.insert(to, row); }) }) .mount(ctx);
// A selection, whose rows are dragged together.SortableList::new(rows) .selected(selected) .on_reorder(|from, to| ..) .on_reorder_many(move |rows, to| sections.update(|order| move_rows(order, rows, to))) .mount(ctx);
// Rows that hold what is pressed itself are dragged by their grip alone.SortableList::new(settings.map(|name| SortableItem::new(name, name).trailing(switch(name)))).handle_only(true);| Builder | |
|---|---|
new(items) | The rows in the app’s order: (value, title), or SortableItem::new(value, title) with description, icon, trailing, disabled, id and key |
on_reorder(handler) | Told (from, to) when a person moves one row: where it was and where it goes, as it is taken out and put back, rows.insert(to, rows.remove(from)), as a strip of tabs tells it. The app reorders its rows |
on_reorder_many(handler) | Told (&rows, to) when several selected rows are moved together: where they were, in order, and where the first of them goes in the list without them. ui::move_rows(&mut list, rows, to) does it to a Vec |
selected(Signal<Vec<T>>), selected_controlled(values, on_selected_change) | The rows that are selected, bound or held by the app. A list without it has no selection. on_selected_change(&[T]) hears each change a person makes |
handle(bool), handle_only(bool) | Whether each row has its grip (it has unless told otherwise), and whether a row is dragged by its grip alone and not by the rest of it |
label(&str) | What the list is called to what reads the tree |
disabled(bool), state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. force draws the row Tab stops on so |
mount(ctx) | In place of converting it: the list keeps a drag from one render to the next, and draws it |
- The list does not keep the order: the app’s rows do, and it shows them in the order it is given. A row is a list item in the list’s dress, so it has a list item’s two lines, its veils, its ring and its heights at each density.
- A press that moves past a few pixels is a drag. The row follows the pointer over the list, turned a little (
ui::SORTABLE_LIST_TILT) under the theme’s large shadow and narrower than the list by what theLiftedpart says (40, taken off about the pointer, so what was under it stays under it); what stood in its place is a ghost; and a line with a dot at its start stands in the flow of the list between the rows it would go between, which move apart to make room for it: the room between two rows is aSlot, which opens round the line over the theme’s base duration in its standard easing, at once where motion is reduced, and closes again when the line goes. The list is as much higher while the line shows. Where letting go would move nothing there is no line. Let go, the app is told where; let go where it was, nothing. Escape puts it back, and the release that follows tells nothing. A drag that moved presses and selects nothing. - The list is one stop of Tab. Up and Down move the focus through the rows. Alt with Up or Down moves the focused row one place, Alt with Home or End to the first or the last, and the focus goes with it. A disabled row is passed by, is not moved, and other rows are put before and after it.
- With a selection a press selects a row, with Ctrl (Cmd) one in or out and with Shift the rows from the last selected, Space adds the focused row or takes it out, Shift with the arrows selects on the way, and Ctrl+A selects them all. A drag of a selected row, or Alt with a key on it, moves every selected row together: each leaves a ghost, the row under the pointer counts them in a badge on its corner, they land together in their order, and the app is told by
on_reorder_many. One row moved, selected or not, is told byon_reorder. - Converted into an element on its own the list keeps nothing: a drag still tells where the row was let go, with nothing drawn on the way.
- To what reads the tree it is a
listoflistitems, or with a selection alistbox(a11y_multiselectable) ofoptions witha11y_selected; each row saysa11y_posinsetanda11y_setsize. - Parts:
SortableListPart::Root(the room between the rows),Item(laid over the list item’s root),Handle,Icon,Title,Description,Ghost,Slot(the room between two rows, before the first and after the last, where the line shows),Line,Cap(the dot at the line’s start),CountandLifted(what holds the row under the pointer). States of a row:SortableListState::Selected,Dragged(the row drawn under the pointer),Disabled. - In the design the rows are 4 apart, each 36 high on
Cardin an edge of 1 inBorder,radius-md, with a grip of 14 inMutedForeground6 from its start, its text 8 after it at 13 and 10 from its end. The ghost is onMutedin an edge of 1 inInputat 0.6; the line is 2 inInfowith a dot of 6, 4 from the row over it and 4 from the row under it, so those two are 10 apart; the row under the pointer is 260 over a list of 300; the count is a disc of 20 inInfowith its number in white at 11 and 600, 4 past that row’s end and 8 over it. A selected row is onHighlight. - A theme’s renderer is given
SortableListView:view.rows(each aSortableRowwith its title, whether it is selected, disabled, a ghost, dragged),view.list(),view.slot(index, count),view.line_at(),view.line(),view.lifted(row),view.dragged()andview.dragged_count(); on a rowrow.handle()androw.render().
Selection Marquee
Section titled “Selection Marquee”The rectangle a person drags over a surface to select what it touches: the tiles of a grid, the files of a folder, the nodes of a canvas.
use lurq::ui::SelectionMarquee;
// selected, before: Signal<Vec<usize>>SelectionMarquee::new(tiles) // What was selected when the drag began: what Shift adds to, and what Escape puts back. .on_start(move |_| before.set(selected.get_untracked())) .on_change(move |marquee| { let touched = (0..count).filter(|tile| { let (x, y, width, height) = place(*tile); marquee.touches(x, y, width, height) }); selected.set(marquee.select(&before.get_untracked(), touched)); }) .on_cancel(move || selected.set(before.get_untracked())) .mount(ctx);
// In a scroll container the marquee wraps what scrolls, and is given the container's state.ScrollVertical::new(SelectionMarquee::new(tiles).scroll(&state).mount(ctx)).with_scroll_state(state.clone());| Builder | |
|---|---|
new(child) | The app’s surface: what the rectangle is dragged over |
on_start(handler) | Told the rectangle once, as a drag becomes a marquee: where the app keeps what was selected before it |
on_change(handler) | Told the rectangle (&Marquee) each time it changes, the first too: as the pointer moves, and as the surface scrolls under it |
on_change_end(handler) | Told the last rectangle when the button comes up; not for a marquee Escape ended |
on_cancel(handler) | Told when Escape ends a marquee: where the app puts back what was selected before it |
scroll(&ScrollState) | The state of the scroll container the surface is in: the rectangle keeps its start on the content while the container scrolls under the drag |
rect(x, y, width, height) | Draws the rectangle at a place with nothing dragging it: for a gallery, a test |
label(&str) | What the surface is called to what reads the tree |
disabled(bool), state(name, on), style(part, ..), rules(&recipe), id, key | As a button has them. id is the surface’s, and the rectangle has it with -marquee |
mount(ctx) | In place of converting it: the marquee keeps a drag from one render to the next, and draws the rectangle |
- The marquee draws nothing and takes nothing until a press on its surface moves past a few pixels: a press that does not is the press of what is under it. From then the rectangle runs from where the button went down to the pointer, kept on the surface, and the release presses nothing.
- A
Marqueeisx,y,widthandheightin the surface’s own coordinates (from the top left corner of what the marquee wraps, whatever it is scrolled to) andmode, what the keys held at the press ask for:MarqueeMode::Replacewith none,Addwith Shift,Togglewith Ctrl (Cmd).touches(x, y, width, height)says whether it shares some room with a box of the surface,contains(..)whether the box is wholly in it,touches_element(&element_ref)the same of an element of the surface by where it is laid out, andselect(&before, touched)what is selected with it: the touched alone,beforeand the touched, orbeforewith each of the touched put in or taken out. - What is selected is the app’s: the marquee tells the rectangle and keeps no selection. A press of the surface’s own room that is no drag is the app’s too, which selects none there.
- Escape ends a marquee under way and tells
on_cancel; the release that follows tells nothing. - Something on the surface that is dragged itself (it has
on_drag_*handlers) keeps its drag: a press on it starts no marquee. - In a scroll container the marquee is what scrolls. A drag held at the container’s edge scrolls it, faster the further the pointer is past the edge (the engine’s
drag_autoscroll), and with the container’s state the rectangle keeps its start on the content and grows over what comes into sight. - Converted into an element on its own the marquee keeps nothing: a drag still tells the app its rectangle, and none is drawn.
- Parts:
SelectionMarqueePart::Root(the surface, which the recipe gives nothing) andMarquee. States:SelectionMarqueeState::Active(a rectangle is drawn) andDisabled. - In the design the rectangle is on
InfoMutedin an edge of 1 inInfo, the whole of it at 0.55. - A theme’s renderer is given
SelectionMarqueeView:view.rect(the rectangle to draw, if any),view.root()(the surface with the drag),view.marquee()andview.render().
Highlight
Section titled “Highlight”A text with marks on ranges of it: the matches of a search, one of them the current one.
use lurq::ui::{FindOptions, Highlight, find_matches};
let options = FindOptions { match_case: case.get(), whole_word: whole.get(), regex: regex.get() };let found = find_matches(&document, &query.get(), options).unwrap_or_default();let current = (!found.is_empty()).then(|| current.get().min(found.len() - 1));// A find in a text keeps the text's weight: it must not wrap again as the query is typed.Highlight::new(&document).marks(found).current(current).keep_weight(true).mount(ctx);
// A mark in a sentence, its words at the board's 500.Highlight::new("Results for backdrop blur in docs").mark(12..25);| Builder | |
|---|---|
Highlight::new(&str) | The text, with no marks yet |
mark(Range<usize>), marks(..) | A mark on a range of the text, in bytes, after the ones it has |
current(Option<usize>) | Which mark is the current one, by its index: drawn stronger |
keep_weight(bool) | The marks’ words keep the text’s weight, whatever the recipe gives Mark and Current: the find in a text. Without it they are the board’s 500 |
mount(ctx) | Puts it in the tree of ctx’s component, which brings the current mark into view each time it changes (Ctx::scroll_range_into_view), and not as the text is first shown. build(theme) and From<Highlight> for Element draw it with nothing kept |
state(name, on), style(part, ..), rules(&recipe), id, key | As a button has them; the id is the text’s |
find_matches(text, query, FindOptions) -> Result<Vec<Range<usize>>, FindError> | |
|---|---|
FindOptions::match_case | The case of the query’s letters counts; without it they match whatever their case, of any script |
FindOptions::whole_word | A match has no letter, digit or _ right before or after it |
FindOptions::regex | The query is a regular expression, with lurq’s regex feature: FindError::InvalidPattern for one that is not, FindError::RegexUnavailable without the feature. A match of no length is passed over |
- The marks are the text’s highlights (
Text::highlights, see Text Styling): they follow their words as the text wraps, and a mark over the end of a line goes on at the start of the next. A mark’s words are of the weight of theMarkpart’s style (Current’s for the current one), 500 by default: the text is drawn in runs, each mark’s words in its weight, and the fill is behind them as they are laid out. Heavier words are wider, so the text wraps otherwise than without the marks: a find in a text, where the marks change with each letter typed, keeps the text’s weight withkeep_weight(true), and the text is then shaped and laid out as without them. Nothing searches for the app unless it callsfind_matches: it keeps the query, the matches and the current one. - Parts:
HighlightPart::Root(the text’s type and color),Mark(its fill, its radius, its padding, its words’ weight),Current(in place ofMark, with its edge). - In the design (
Highlight) the text is 14 in the foreground and a mark is on the muted warning fill, of a radius of 2, reaching 3 past its words and 1 above and below. The board draws no current mark: it is the mark with an edge of 2 in the warning color, which reads in both appearances where a fill of the warning color would not under the text’s own color. A mark’s words are 500, as the board’s; a face without a 500 draws its nearest, as the system’s sans on Windows does with 400. - A renderer that draws another highlight gets a
HighlightView:fill(range, part)is a mark as aTextHighlightin a part’s style,fills()every one.
Tree View
Section titled “Tree View”Things inside things, one level under the other: the files of a project in their folders, the layers of a scene, settings in their groups.
use lurq::ui::{TreeItem, TreeView};
// open: Signal<Vec<&str>>, selected: Signal<Option<&str>>TreeView::new(selected, [ TreeItem::folder("crates", "crates").items([ TreeItem::folder("lurq", "lurq").items([ TreeItem::file("lib.rs", "lib.rs"), TreeItem::file("theme.rs", "theme.rs"), ]), ]), TreeItem::file("Cargo.toml", "Cargo.toml"),]).label("Files").open(open).on_activate(|file| open_file(file));
// Any number selected, with Ctrl and Shift.TreeView::multiple(many, project).open(open);
// The selection held by the app, which is told each new one.TreeView::controlled(app.selected(), project, |row| app.select(row));
// Children the app brings when the row is first opened.TreeItem::folder("registry", "registry").lazy(true);
// What stands at a folder's end while its row is pointed at or focused.TreeItem::folder("src", "src").trailing(new_file_button).trailing_on_hover(true);
// Ten thousand rows: in the engine's virtual list, which builds those in view.TreeView::new(selected, items) .open(open) .style(TreeViewPart::Root, |s| s.height(480.0)) .mount(ctx);| Builder | |
|---|---|
new(selected, items) | The rows at the top, each a TreeItem<T> with what it holds, of which one is selected at most, bound to a Signal<Option<T>>. T is what rows are told apart by: a path, an id |
multiple(selected, items) | The same of which any number are selected, with Ctrl and Shift as a list of files has them, bound to a Signal<Vec<T>> |
controlled(selected, items, on_change), controlled_multiple(selected, items, on_change) | The selection held by the app: an Option<T> of one row, told on_change(&row), or the rows of any number, told on_change(&[rows]); the tree shows what the app gives back. Two built at the one place in the app’s code, in a loop, are told apart by their id or key |
TreeItem::new(value, label), folder(value, label), file(value, label) | A row; a folder has the icons of a folder and of an open one, a file the icon of a file |
TreeItem::icon(icon), open_icon(icon) | The icon before the label, and another while the row is open: a name, or None for none in place of a folder’s or a file’s |
TreeItem::trailing(element) | What stands at the row’s end: a count, a badge |
TreeItem::trailing_on_hover(bool) | What stands at the row’s end shows only while the row is pointed at or the focus is in it, and always at the touch density: an action |
TreeItem::items(items), item(item) | What the row holds |
TreeItem::lazy(bool) | It has children the app brings when it is first opened: it opens as a folder does, with a spinner in place of its chevron while it is open with none |
TreeItem::disabled(bool), id(id), key(key) | A row that takes nothing; the id of the row’s element; what the row is told apart by among the rows in place of its place, which keeps its node and its focus in a virtual list as rows are put in before it |
open(Signal<Vec<T>>) | The rows that are open. Opening a row adds it, closing one takes it out |
open_ids(ids, toggle) | The same held by the app: toggle(&value, open) is told of each row a press or a key asks to open or close |
guides(bool) | A line down each level, under the chevron of the row it is in |
label(&str) | What the tree is called, to what reads the tree. It draws nothing |
on_change(handler) | Told the row a click or Space selects (&T), or, of a tree of any number, the whole new selection (&[T]) after a click, Space, Shift with a key or Ctrl+A changed it; not for what was selected already, nor when the app sets it. The tree is TreeView<T, OneSelected> or TreeView<T, ManySelected>, so a handler of another type does not compile |
on_activate(handler) | Told of the row a double click or Enter activates, or in the touch form (ui::touch_form()) a tap, never held back for a second: open the file. A row that opens opens or closes as well |
on_open_change(handler) | Told of each row a press or a key opens or closes, (&value, open): where a lazy row’s children are brought |
disabled(bool), state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. id is the id of the root; force draws the row Tab stops on so, the first selected, else the first that is not disabled |
mount(ctx) | In place of converting it: the tree in the engine’s virtual list, for thousands of rows. Give it a height |
- What is open and what is selected are the app’s, as an accordion’s open items are: a signal the tree reads and writes, or the app’s own state and a handler. The rows are one flat list of what is shown: what a closed row holds is not built.
- A row opens and closes as an accordion’s item does, and as a property grid’s category: over the theme’s base duration and its standard easing, at once where motion is reduced. What it holds slides open under it and what is below moves with it, its rows fade in and out, and its chevron turns. Pressed again on the way (Left on an opening row, Right on a closing one, its chevron), it turns round from where it is. The keys and the focus work all through it: Up, Down and typeahead pass by the rows of a closing row, which are reached neither by Tab nor by the arrows. In a tree that builds every row, what a row holds is in its panel, whose height runs; in a mounted tree each row’s height runs from nothing to its own in its turn, the rows coming into view built as they come and those of a closing row kept, inert, until they have closed, so that a row of thousands opens and closes building only the rows in view, the first of them in turn and the rest with the last. A tree has no drag of its rows, so nothing opens under a drag at rest.
- A click of a row selects it, as the button comes up over the row it went down on, so a press dragged off the row selects nothing; a press of its chevron opens or closes it (and does not select it), a double click activates it. With
multiple, a press with Ctrl (Cmd) adds the row or takes it out, one with Shift selects the rows from the last selected to it. The last of the selection is where a range starts. - The tree is one stop of Tab, at the selected row or the first. Up and Down move through the rows that are shown, Home and End to the first and the last, without going round. Right opens a closed row and goes into an open one; Left closes an open row and goes out of a closed one or a leaf to the row it is in;
*opens every row at the focused one’s level. A letter goes to the next row that starts with it. Space selects the focused row (withmultipleit adds it or takes it out; with Shift it selects to it), Enter activates it. Withmultiple, Shift with Up, Down, Home or End moves and selects the rows on the way, and Ctrl+A selects every row shown. A disabled row is passed by. - The keys are the engine’s: the tree is a focus group that is
nested,one_stop, withtypeaheadand withoutwrap, and each row says its level and whether it is open withfocus_levelandfocus_expanded. A list of items in items (a sidebar’s) gets the same keys the same way. mount(ctx)puts the rows in the engine’s virtual list, which builds the rows near its view: a tree of ten thousand rows costs about one screen of them. The keys still reach every row: the tree gives its rows to its focus group (FocusRows), so Up, Down, Home, End, PageUp and PageDown (a view of rows), Right, Left,*and typeahead go to any row, the list builds and shows the row they go to, and the focus goes to it once it is built. Shift with them and Ctrl+A select over every row. The list fills the tree, which is given a height; its rows are drawn byTreeRow::render, so a theme’s rules reach them and its renderer of the whole tree does not.- What an item marks with
trailing_on_hoveris in aRevealpart, hidden at rest and shownwithinthe row: each row is an interaction group (interaction_group), lit while the pointer is on it or the focus is in it. At the touch density, where nothing points, it always shows. - To what reads the tree it is a
tree(a11y_multiselectablewithmultiple) oftreeitems, each witha11y_level,a11y_posinsetanda11y_setsizeamong the rows of its level in its row,a11y_selected,a11y_expandedwhere it opens anda11y_busywhile its children are on their way. - Parts:
TreeViewPart::Root(the rows, one under the other),Row(what is pressed, selected and focused),Indent(one step of a row’s indent, for each level it is in),Guide(the line in a step),Content(what a row holds after its indent),Chevron(also the room of one in a row that does not open, and the spinner’s),Icon,Label,Trailing,Reveal(around what is at the end of a row marked to show it on hover),Panel(what opens and closes under a row that opens, in a tree that builds every row) andBody(its rows, which fade). States of a row:TreeViewState::Selected,Open,Disabled; a row’sOpengives its panel its height. - In the design a row is 28 high, 2 under the one before, with
radius-smand 8 at each side; each level moves it in by 16. It holds a chevron of 14 inMutedForeground(down while it is open, turned to the right while it is closed), an icon of 16 inMutedForegroundand its label in the body’s type at 13, 6 apart. The selected row is onHighlight, its label at 500 and its icon inForeground. Under the pointer and held down a row has theStateHoverandStatePressedveils, the focus from the keyboard is a ring of 2 inRinginside it, and a disabled row is half opaque. A guide is a line of 1 inBorderunder the middle of the chevron of the row it is in, as high as a row and the room under it. What is at a row’s end is 12 inMutedForeground. - A row follows the density: 20, 28 (the design’s), 36 and 40 high at compact, default, comfortable and touch, its guide with it.
- A theme’s renderer is given
TreeViewView:view.rows(each aTreeRowwith its label, level, position, whether it opens, is open, is loading, is selected, is disabled, its icon and what is at its end),view.root()(the column with the keys and its role) and, on each row,row.button()(the behavior with the row’s style),row.indent(),row.chevron(),row.icon(),row.label()androw.render(). It is set forTreeView<T>of anyT:theme.set_renderer::<TreeView<String>>(..)draws trees of every id.
Navbar
Section titled “Navbar”The way round a site or an app along the top of its window: the brand at its start, its links, and a search, actions and who is signed in after them.
use lurq::ui::{Avatar, NavItem, NavLink, NavPanel, Navbar, NavbarBrand, SearchField, TextBoxSize, icons};
Navbar::new() .label("Main") .brand(NavbarBrand::new("lurq").icon(icons::BOX).on_select(move || go_home())) .item( NavItem::new("Docs").current(at_docs).panel( NavPanel::new() .columns(2) .link(NavLink::new("Getting started").description("Install lurq and open your first window.").href("/docs")) .link(NavLink::new("Theming").description("Roles, palettes and dark mode.").href("/docs/theming")), ), ) .item(NavItem::new("Components").href("/components")) .item(NavItem::new("Blog").href("/blog")) .trailing(SearchField::new(query.clone()).placeholder("Search").size(TextBoxSize::Sm)) .trailing(account) // an Avatar that opens a Menu .sticky(true) .mount(ctx)Navbar | |
|---|---|
brand(element) | What stands at its start: a NavbarBrand (an icon(name) or the app’s media(element), a logo, beside a name, pressed where it has on_select; with state, style, rules, force, id and key), or an element of the app’s |
item(NavItem), items(..) | A link after the others; one with a panel opens a panel of links, as in a navigation menu |
trailing(element) | What stands after the links, after what stands there: a search field, a button, an avatar with its menu |
sticky(bool) | It stays at the top of the page that scrolls it |
open(signal), on_open_change(handler) | Which item’s panel is open, by its index: the app’s Signal<Option<usize>>; and what hears it change. Without a signal the bar keeps its own |
menu_open(signal), on_menu_open_change(handler) | On a narrow window, whether the links are open over the page; and what hears the menu button turn it |
narrow(bool) | Whether its links are behind the menu button, whatever the window’s width: they are below the md breakpoint unless told |
label(&str) | What the navigation region is called to tooling: “Main” unless told |
menu_label(&str) | What the menu button of a narrow window is called to tooling: “Menu” unless told. Whether the links are open it says with a11y_expanded |
state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. id is the bar’s; its links are {id}-links (the items {id}-links-0 and on, a panel {id}-links-0-panel), the menu button {id}-menu, the links over the page {id}-drawer |
- It is mounted (
mount(ctx)): its links are a mounted navigation menu, and on a narrow window a mounted sidebar. Converted into an element on its own it is drawn with what the signals it is given say, for a gallery or a test. - The links take the room the bar has to spare and no more: where they do not fit they are cut at its end, and never run under what stands after them, which keeps its width. A bar that has more than its window’s room for its links is one for
narrow(true). - Its links are a navigation menu in its links variant: each a stop of Tab, the page shown (
NavItem::current) in the foreground and the others in the muted foreground, brought forward under the pointer. One with a panel opens it under the bar by a press, under the pointer after a moment, and with Enter, Space and Down, with all a navigation menu does. - On a window narrower than the
mdbreakpoint (or wherenarrow(true)says) the links go behind a ghost button of themenuicon at the bar’s start, called “Menu” (menu_label), into aSidebarover the page, which slides in from the start over a veil: each link an item, the page shown selected, an item with a panel an item that holds its links, open, in from it, with the items after it beside it. Choosing one closes it, as Escape and a press on the veil do. The brand and what stands after the links stay in the bar. - In the design the bar is 56 tall in
Background, with a line of 1 inBorderalong its bottom, padded 16 at its sides with 24 between what it holds. The brand is a mark of 20 inForeground8 before its name in 16/600; the links are 20 apart in 13/500; what stands after them is 24 apart. On a narrow window it is padded 8 with 8 between what it holds. - Parts:
NavbarPart::Root,Brand,BrandMark,BrandName,Links(the room of the links, which takes what the bar has to spare),Trailing. States:NavbarState::Narrow,Sticky,Interactive(the brand is pressed). How its links look is the navigation menu’s recipe, in itsLinksvariant: a theme restyles them there, into the board’s tablet tab bar, say (a bar onMutedwith the full radius, its items 36 tall and round, the page shown onBackgroundwith a shadow). - To what reads the tree the bar is a
navigationcalled by its label, its linkslinks (the page shown witha11y_currentpage) orbuttons that open a panel, and the menu button abuttonwitha11y_expandedanda11y_controlsnaming the links over the page. - A renderer for
Navbargets aNavbarView:view.root()is the bar with its style and its role;brand,links,trailing,menu_buttonanddrawerare what it holds, built, to put in it.view.render()builds the bar.
Navigation Menu
Section titled “Navigation Menu”The way round a site along a row of links, some of which open a panel of links under them: Docs, Components, Blog.
use lurq::ui::{Card, NavItem, NavLink, NavPanel, NavigationMenu, icons};
NavigationMenu::new() .label("Site") .item( NavItem::new("Docs").panel( NavPanel::new() .columns(2) .featured(Card::new().title("lurq 0.62").description("A navbar, a navigation menu and a sidebar.")) .link(NavLink::new("Getting started").description("Install lurq and open your first window.").icon(icons::PLAY_CIRCLE).href("/docs")) .link(NavLink::new("Theming").description("Roles, palettes and dark mode.").href("/docs/theming")), ), ) .item(NavItem::new("Blog").href("/blog")) .open(open.clone()) .mount(ctx)NavigationMenu | |
|---|---|
item(NavItem), items(..) | An item after the others |
open(signal) | Which item’s panel is open, by its index: the app’s Signal<Option<usize>>, which a press, the pointer and the keys set, and Escape, a press outside, a choice and the pointer going clear set to None. Without one the menu keeps its own |
on_open_change(handler) | What hears a panel open, another take its place, or the open one close |
variant(impl Into<Name>) | A NavigationMenuVariant, or a variant a theme’s recipe names. Menu, the board’s: each item a box lit under the pointer and while its panel is open. Links: the text alone, as a navbar has it |
open_delay(..), close_delay(..) | How long the pointer rests on an item before its panel opens (the theme’s base duration), and how long a panel stays after the pointer has left it and its item (the slow one) |
disabled(bool), label(&str) | No item can be pressed; what the navigation region is called to tooling, “Main” unless told |
state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. id is the row’s; its items are {id}-0 and on unless they have ids of their own, each panel {id}-0-panel, its links {id}-0-0 and on |
NavItem, NavPanel, NavLink | |
|---|---|
NavItem::new(label) | A link: href(path) (the router’s), on_select(handler), current(bool), icon(name), disabled(bool), id, key. With panel(NavPanel) it opens a panel in place of going somewhere, and has a chevron |
NavPanel::new() | link(NavLink), links(..); columns(n), the first filled first (one unless told); featured(element), a column of its own before the links: a card |
NavLink::new(title) | description(&str) under its title, icon(name) at its start, href(path), on_select(handler), current(bool), disabled(bool), id, key |
- It is mounted (
mount(ctx)): it keeps the timers of its delays, where the pointer is and how the open panel was opened. Converted into an element on its own it opens its panels by a press and the keys, from the signalopengives. - The pointer: a press of an item with a panel opens the panel, and a press again closes it; resting on the item opens it after the open delay (a press that follows keeps it). One panel is open at a time, and with one open the pointer coming onto another item opens that one at once. The panel stays while the pointer is on the item, on the panel or crossing the 6 between them, and closes when it has left them for the close delay; a press outside it closes it and goes on to what it is on. Choosing a link closes the panel first, and then runs it and goes to its path: a handler that opens a dialog keeps its focus.
- The keyboard: each item is a stop of Tab, as links on a page are, and Left and Right move between the items as well. Enter, Space and Down open an item’s panel with the focus on its first link (Down on an item whose panel the pointer opened takes the focus into it); Up and Down go through the panel’s links, column after column; Left and Right close it and go to the item beside it, opening that one’s panel where it has one and only focusing a link, which is not followed; Escape closes it with the focus back on its item. Tab goes from an item into its open panel and from its last link on to what follows the item, closing the panel; the focus leaving the item and the panel closes it. Alt does nothing to it.
- Under the pointer, focused from the keyboard, or with its panel open, an item is filled with
Highlight, the board’saccent; the page shown, or an item whose panel holds it, is onMuted. In the design an item is 36 tall, padded 12 with the medium radius, its text 13/500 inForeground, and an item with a panel has a chevron of 14 inMutedForeground6 after it, up while its panel is open; the items are 4 apart. The panel opens 6 under its item, from its start, inPopoverwith an edge of 1 inBorder, the large radius and the medium shadow, padded 8 with 8 between its columns, each 208 wide; it fades in over the theme’s base duration and out over the fast one. A link is padded 12 with the medium radius, its title 14/500 over its description 13 inMutedForeground, 4 apart and 1.4 high, an icon of 16 inMutedForeground12 before them; it is lit withHighlightunder the pointer and focused. In theLinksvariant an item is its text alone, 32 tall, 20 apart, inMutedForeground, inForegroundunder the pointer, while its panel is open and where it is the page shown, with the focus ring around it; its panel opens 18 under it, 6 past the edge of a navbar. - The engine’s part is
FocusGroup::panel_row(true), which the row has: a row of menus whose elements are links as well as buttons. Left and Right in an open panel that nothing in it takes close it and focus the element beside it, asking it to open where it says it opens and closes (focus_expanded(open, toggle)), and press nothing; Alt is a menubar’s, not its. - Parts:
NavigationMenuPart::Bar,Item,ItemIcon,Label,Chevron,Viewport(the room between an item and its panel, which keeps the panel under the pointer),Panel,Column,Featured,Link,LinkIcon,LinkText,LinkTitle,LinkDescription. States:NavigationMenuState::Open,Current,Disabled; variants:NavigationMenuVariant::Menu,Links. - To what reads the tree the row is a
navigationcalled by its label (in a navbar, alistin the navbar’s), an item alink(witha11y_currentpagefor the page shown) or abuttonwitha11y_expandedanda11y_controlsnaming its panel, the panel agroupcalled by its item, and its linkslinks with their description. - A renderer for
NavigationMenugets aNavigationMenuView:view.bar()is the row with its style, its role and its focus group;view.item(index)an item’s behavior with its style,view.item_icon(index),view.label(index)andview.chevron(index)what it holds, andview.panel(index)its panel hung from it, to put after it (view.panel_content(index)is the panel alone);view.item_part(index, part)is the style of a part of one item.view.render()builds the menu.
In a narrow room. A menu is as wide as its items and no wider than its room: the items it has no room for
go, the last first, behind a More item at its end (more_label), which opens a menu of them, a link as an item
(the page shown checked) and an item with a panel as its name over its panel’s links. More is an item of the row
to the keys, is drawn as the item of the page shown while that page is behind it, and is gone when every item is
back. A theme’s renderer builds the row of NavigationMenuView::slot and more. Its open panel takes the room a narrow window has: its columns go one under another where two have no room side by side, and none is wider than the window lets it be. The board draws the menu with room for all of it (Navigation Menu, a panel of two columns of 208) and no narrow form: More and the panel of one column are lurq’s.
Rows of the same things in columns: crates and their status, files and their sizes, people and their roles. The columns of the header and of every row are the same widths whatever is in a cell.
use lurq::ui::{Badge, Table, TableColumn, TableSort};
// sort: Signal<Vec<TableSort>>, selected: Signal<Vec<String>>let columns = vec![ TableColumn::new("name", "Name").text(|row: &Crate| row.name.clone()).mono(true).sortable(true), TableColumn::new("status", "Status").width(120.0).cell(|row: &Crate| Badge::new(&row.status).into()), TableColumn::new("size", "Size").width(70.0).numeric().text(|row: &Crate| format!("{} KB", row.size)).sort_key(|row: &Crate| row.size), TableColumn::actions("actions", |row: &Crate| open_button(row)),];// The app gives the rows in the order it wants.let mut rows = rows;TableSort::sort_rows(&sort.get(), &columns, &mut rows);Table::new(columns, rows) .row_key(|row: &Crate| row.name.clone()) .label("Crates") .sort(sort) .selected(selected) .height(320.0) .on_row_activate(|name| open(name));
// Thousands of rows: mounted, it builds those in view.Table::new_shared(columns, rows.clone()).row_key(|row: &Crate| row.id).height(480.0).mount(ctx);| Builder | |
|---|---|
new(columns, rows), new_shared(columns, Arc<Vec<R>>) | The columns and the rows, in the order the app wants them. Shared rows given again at each render are not copied |
TableColumn::new(id, title) | A column that takes a share of the room the others leave |
TableColumn::text(|row| String), cell(|row| Element) | A row’s cell: a text in the cell’s type, or what the app builds (a badge, an avatar and a name) |
TableColumn::width(px), share(f32), fit(), min_width(px), max_width(px) | Its width: in pixels, a share of what is left, or as wide as the widest of its cells shown, between a least and a most |
TableColumn::align(ColumnAlign), numeric(), mono(bool), muted(bool) | Where its content sits; a column of numbers (at its end, mono 12 in the muted color); its text in the mono type or the muted color |
TableColumn::wrap(bool) | Its text wraps onto as many lines as it needs, and its row grows to hold them, never lower than a row |
TableColumn::sortable(bool), sort_by(|a, b|), sort_key(|row|) | A press of its header sorts the rows by it; what TableSort::sort and TableSort::sort_rows compare rows by |
TableColumn::pin(ColumnPin) | Where the column stays while the rows scroll sideways: Start (the first columns, after the checkboxes) or End (the last columns, a row’s actions); None unless told |
TableColumn::resizable(bool) | Whether a person makes the column wider or narrower: as the table says unless told |
TableColumn::editor(CellEditor) | How a data grid edits its cells; a table shows them |
TableColumn::controls(bool), TableColumn::actions(id, cell) | Its cells hold what is pressed, and a press of it is not the row’s; a column of a row’s buttons at its end |
row_key(|row| K) | What tells a row apart, which the selection and the handlers name it by. Without it, a row’s place |
sort(Signal<Vec<TableSort>>), sort_controlled(sort, on_change) | What the rows are sorted by, the first column first, the app’s signal or its value: a press of a sortable header sorts by its column alone, through ascending, descending and none; with Shift it adds the column after the others, turns it, then takes it out |
on_sort_change(|sort: &[TableSort]|) | Told the new sort at each press of a sortable header, bound or not; a second handler is called after the first |
selected(Signal<Vec<K>>), selected_controlled(keys, on_change) | The rows selected, the app’s signal or its value, with a column of checkboxes |
on_selection_change(|keys: &[K]|) | Told the whole new selection after a press or a key that changes it, bound or not; not for one that leaves it as it is, nor when the app sets the signal |
checkboxes(bool) | Whether a table whose rows are selected has the column of checkboxes; without it a press of a row selects it |
reveal(key, request) | A mounted table brings the row of key into view, once for each new request: for a row the app selects from outside the table. It scrolls the least that shows the row and makes it the row Tab stops on; asking again with the same number does nothing |
on_row_click(handler), on_row_activate(handler) | Told of a press of a row, and of a double press or Enter; in the touch form (ui::touch_form()) a tap selects and activates the row at once, never held back for a second |
density(Density) | Rows of 36 compact, 44 at the default, 52 comfortable and touch |
height(..), max_height(..) | The table’s height: the header stays and the rows scroll under it |
empty(element), empty_text(&str) | What stands under the header where there are no rows: by default an empty state that says “No rows”, or the app’s words |
select_all_label(&str), select_row_label(&str) | The names of the header’s checkbox and of a row’s: “Select all” and “Select row” unless told |
count_text(|count: TableCount| String) | What the footer’s count says, given how many rows it shows (count.shown), how many there are (count.total) and how many are selected (count.selected): “24 rows”, “3 of 24 rows selected”, filtered “12 of 340 rows” unless told |
filters(Signal<TableFilters>), filters_controlled(filters, |filters| ..), on_filters_change(|filters: &TableFilters| ..) | What the rows are filtered by: a filter for each column filtered, which the table applies to the rows it is given (see the data grid) |
loading(bool), loading_rows(n) | Rows of skeletons under the header while the rows are on their way |
pagination(element), count(bool), total(n) | A footer that counts the rows and what is selected, with the pagination at its end |
resizable(bool), on_column_resize(|id, width|), on_column_resize_end(|id, width|), resize_label(|title| String) | Columns made wider or narrower by a person (off unless told): told while a column moves and when it is done; what a resizer is called, “Resize Name” unless told |
mount(ctx) | The table mounted: it builds the rows and the columns in view and a few around them, and keeps its columns’ measured widths and the widths a person made them |
label(&str), disabled(bool), state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. A row’s id is the table’s with -row- and its place; a header’s -header- and its column’s id; the header’s checkbox -select-all |
- What the rows are, their order, what is selected and what they are sorted by are the app’s. A press of a sortable header asks for the rows sorted by it alone, ascending, then descending, then not at all; a press with Shift adds its column to the sort after the others, ascending, or turns it in its place to descending, then takes it out (
TableSort::after_press). Where the rows are sorted by more than one column, each sorted header shows its place in the sort after its arrow (TablePart::SortOrder, mono 11 inMutedForeground). The app gives the rows in that order:TableSort::sort_rows(&sort, &columns, &mut rows)sorts them by the first column, the rows equal in it by the next, each by its key or its text, andTableSort::sortby one. A column’s menu sorts by its column alone, and its “clear” takes the column out of the sort. - With a selection a table has a column of checkboxes. A press of a row selects it alone, with Ctrl (Cmd) adds it or takes it out, with Shift selects the rows from the last selected one to it; a press of its checkbox adds or takes it out, with Shift the range. The header’s checkbox selects every row the table shows, or none where all are, and is mixed while some are. A press in a column of
controlsis the control’s alone. - The header stays while the rows scroll in the table’s own height, and a table wider than its box scrolls sideways, its header with it, the scroll bars beside the rows and not over the header or the pinned columns: the bar down runs under the header at the table’s end edge, over the edge of a column pinned at the end and never over a column that scrolls, the bar across runs between the columns pinned at the start and at the end and has a strip of its own under the rows while they are wider than the box, so no row is under it (a table whose columns fit has none). The first columns pinned at the start stay there after the checkboxes, each after the ones before it, and the last ones pinned at the end stay at the end; a pinned column after the first is best given a width of its own, since where it stays is reckoned from the widths of the pinned ones before it. Converted into an element a table builds every row; mounted (
mount(ctx)) it builds the rows in view and a few around them, and of those the cells of the columns in view, two past each side, the pinned ones and the focused one, a run of columns not built standing as one room across their tracks (in_tracks): a million rows of two hundred columns cost about what a screen of them does, and so does each render. Before it knows how wide it is it builds the columns a wide window shows, not all of them. The keys of the rows are reckoned for the rows built and those a selection or a range names; where a selected key is looked up among the rows (the header’s box, a range by Shift), a mounted table makes an index of the keys once for the rows it is given and keeps it while they are the same rows, so give them shared (new_shared) where there are many: given anew at each render, the rows are new to it each time. Grouped rows are laid out once for the rows, the columns grouped by and the groups open. Where a column wraps (TableColumn::wrap), the rows not built are taken to be a row high, those built are measured as they are laid out, before they are painted, and a row above the view that is higher or lower than it was taken to be moves the scroll by as much: what is in view stays still as heights become known, and the bar’s thumb dragged anywhere lands among the rows it says. A table with no height builds every row either way. - A resizable column has a resizer at the end of its header, in the room after the column: dragged, it makes the column wider or narrower between its least (48 at the least) and its most, and Ctrl with Left or Right on the column’s header does it by 10 (50 with Shift). The resizer is a
separatorto what reads the tree, with the column’s width asa11y_valuenow; its line of 2 inRingshows under the pointer and while it is dragged. A mounted table keeps the widths a person made; a header’s title ends in an ellipsis where its column is too narrow for it. - The columns are one list of tracks for the header and every row (
ColumnTracks), measured from the rows that are built: a column sized by its content is as wide as the widest of its cells shown so far, and does not narrow as rows scroll by. - The rows are one stop of Tab, at the focused, the first selected or the first row. Up and Down move through them, Home and End to the first and the last, and in a mounted table PageUp and PageDown by what is shown. Space selects the focused row (adds it or takes it out), Enter activates it, Ctrl+A selects them all. Tab from a row goes into what it holds that takes the focus, its buttons, and then out of the table. The sortable headers and the header’s checkbox are a stop of their own before the rows, Left and Right between them. A row the keys reach is scrolled into view clear of the header.
- To what reads the tree it is a
table, or agrid(a11y_multiselectable) where its rows are selected, witha11y_rowcount(the header’s among them) anda11y_colcount,a11y_busywhile loading; its header and rows arerows witha11y_rowindex(the header’s 1),a11y_selectedwhere rows are selected; a header is acolumnheaderwitha11y_sort(ascending,descending,none) where it sorts; a cell is acell. - Parts:
TablePart::Root(the box),Scroll(what scrolls both ways),Header,HeaderCell,SortIcon,ResizerandResizeLine(a column’s edge),MenuTrigger(what opens a grid’s column menu),DropLine(where a column dragged by its header goes),GroupRow,Chevron,GroupLabelandGroupCount(a group’s row and what it shows),Summary,SummaryLabelandSummaryValue(a summary row and what its cells say),RowNumber(a row’s number and the numbers’ header),Row,Cell,Select(the checkbox column’s cell),Editor(what holds a grid’s editor),Empty,Footer,Count. States:TableState::Selectable,Selected,Last,Sortable,Sorted,Muted,Mono,Numeric,Pinned,Footer,Disabled, and a data grid’s range of cells on its cells:InRange(the range’s fill, on every cell of it but the focused one, the rows of the groups open reckoned as they are shown),RangeTop,RangeBottom,RangeStart,RangeEnd(its edge on that side); and on a grid’s headersOpen(its column’s menu is open),DropBeforeandDropAfter(a column dragged by its header goes before it, or after the last). - In the design the table is a box with
radius-lg, an inner edge of 1 inBorderand theBackgroundfill. The header is 40 high onMutedwith a line of 1 inBorderunder it, its titles 13/500 inMutedForeground; a row is 44 high with the same line under it but the last, its text 13 inForeground. Both are padded 16 at each side with 16 between columns, 12 where the rows have checkboxes, whose column is 16 wide. A sorted column’s title is inForegroundwith an arrow of 14, 4 after it; a sortable one has a muted mark ofchevrons-vertical, and its title is inForegroundunder the pointer. A selected row is onHighlight. A number is mono 12 inMutedForegroundat its column’s end. The footer is 44 high, padded 16 and 8, its count 13 inMutedForeground. Under the pointer and held down a row has theStateHoverandStatePressedveils, the focus from the keyboard is a ring of 2 inRinginside it, and a disabled table is half opaque. - A theme’s renderer is given
TableView:view.headers(each aTableHeaderwithcell(),sort_icon(),render()),view.rows(each aTableRowwith its place, whether it is selected, itscellsandbutton(),checkbox(),render()),view.root(),view.header(),view.select_all(),view.body()(the rows and the room of those not built),view.skeletons(),view.empty(),view.footer()andview.tracks, the list every row of the table lays its cells out in, withview.columns_built(which columns a mounted table built) andin_tracks(built, cells)to lay a row’s cells out with the room of those not built. A header and a cell say theircolumn. It is set forTable<R, K>of anyRandK, a data grid’s too.
In a narrow room. A cell’s text wider than its column ends in an ellipsis unless the column wraps; the whole text is what tooling reads of the cell. The lines of a loading table are shares of their cells, so they end inside a narrow column. A footer too narrow for its count and its pagination puts the pagination under the count. The shares are the board’s (Table/Loading: lines of 150, 190, 120 and 170 in a cell of 176, and 70 in one of 90).
Charts
Section titled “Charts”What every chart of the system stands on, behind the canvas feature: each is drawn on a canvas, its words (the header, the axis, the legend, the tooltip) are elements in the theme’s type, and it is drawn again only when its data, its size, its theme or the point under the pointer changes (Canvas::paint), sharp at any scale.
- Data is the app’s:
ChartSeries::new(name, values), a value for each category, orChartSeries::points(name, points), an x and a y each; numbers aref64. A place in it is aChartPoint { series, index }. - Colors come from the theme: a series takes
Chart1toChart5in turn (series_color(index)), unlessChartSeries::color(..)gives it a role or a color. The grid, the line the values stand on, the cursor and every text are on roles. - The frame is shared: the card (the card’s fill, an edge of 1, the extra large radius, the small shadow), the title over the description, the plot, the axis under it and the legend.
ChartSize::Mdis the board’s Bar Chart (padded 24, 20 between rows, a title of 16 over a description of 13, a plot of 160);Smits other charts (20, 16, 15 over 12, a plot of 140). - The words every chart has, as its builder says them:
title,description,label(the name to tooling, the title’s unless told),size,height(the plot’s),legend(bool)(where it has more than one series unless told),hidden(Signal<Vec<String>>)withhidden_controlledandon_hidden_change(the series a press of the legend’s item hides, by name),value_text(|value| ..)(every number it writes: a tick, a tooltip’s value, what tooling reads),grid(bool)andvalue_axis(bool)(a line at each tick across the plot, and the ticks’ numbers in a room of their own at its start),empty_text,loading,on_select(|point| ..), and the six of every themed builder.build(theme)andFromgive the still chart, drawn and read;mount(ctx)the one that follows the pointer and the keys. - Scales:
LinearScale::nice(values, range, count)maps values onto a length, from a round number at or under the least (zero where none is under it) to one at or over the most, its ticks a step of 1, 2 or 5 times a power of ten apart;BandScalelays categories on bands of equal width with a gap between them. - The pointer and the keys: the pointer finds the point it is on, or the nearest one near enough (
nearest,nearest_sortedfor a line of thousands of points, by halves), and the tooltip shows it. The plot is one stop of Tab: Left and Right go along a series, Up and Down to the series before and after, Home and End to its ends; the focused point shows what a hovered one shows, and a press, Enter or Space tellson_select. - To tooling a chart is a
figurewith its name and its description; its plot is a canvas whose items are its data (a bar’s place, its category and its value as written), which a reader goes through, and whosea11y_valuesays the point under the pointer or the focus. - Motion: the plot moves in as it is first shown and to a change of its data (a series hidden or shown again included), for the theme’s slow duration (
MotionDuration::Slow, easedStandard), and is drawn again at each frame only while it moves; at rest it is drawn only when it changes. Nothing moves where motion is reduced, nor while the chart is resized, andmotion(false)keeps a chart still. A chart’s plot draws itself on its way (ChartPlot::paint_moving, given aChartMotion: what it was, and how far along it is): unless it does, it is revealed from its start as it enters (a line drawn on) and fades to a change. Tooling reads the data where it goes. - States: no data (
empty_text, “No data” unless told), loading (the skeleton as high as the plot), values under zero, values of very different size (the ticks stay round), a long category name (cut with an ellipsis under its band). - A plot whose values run across (
ChartPlot::across, a bar chart lying across) has its grid lines down the plot, its ticks’ numbers under it and its categories’ names at its start. - A chart’s author writes its plot (
impl ChartPlot: what it draws, its ticks, its axis, where its points are, what a point’s tooltip says, its items, a signature of its data) and lays its own parts overchart_recipe();ChartPropsandchart_props!()give its builder the words above, andChartFramebuilds and mounts it. See the module’s docs inlurq::ui. - Its shape, where a plot is not as wide as the frame with the legend under it:
ChartFrame::plot_width(w)andplot_justify(..)(a pie’s or a radar’s square, a grid of cells, at the frame’s start, middle or end),legend_beside(values, size)(the legend beside the plot, one item under another with each value at its end,ChartPart::Bodythe room between them, 20 inMdand 18 inSm; the plot’s tooltip stands over the legend),own_legend(element)(a chart’s own legend in place of its series’, left out where the app turns the legend off and while loading). A plot whose height follows its width (a heatmap’s grid) says it withChartPlot::height_for(width): the frame lays it out at that height and again when the width it is drawn at asks another. Words in the plot’s box areChartLabels (ChartPlot::labels), in the axis’s type unless given a part of the chart’s own; a tooltip’s key in another color than its series’ isChartPlot::tip_color. A point with no rows in its tooltip says its title alone to tooling.
Chart Legend
Section titled “Chart Legend”The board’s Chart Legend: a key in each series’ color and its name, in a row that wraps.
use lurq::{app::theme::PaletteColor, ui::{ChartLegend, ChartLegendItem, ChartLegendShape}};
ChartLegend::new([ ChartLegendItem::new("Layout", PaletteColor::Chart1), ChartLegendItem::new("Text", PaletteColor::Chart2),]).shape(ChartLegendShape::Dot)- Square keys of 10 with corners of 2 and the names 12 in
Foreground, 16 between items, 6 between a key and its name;ChartLegendShape::Dothas the dots of 8 and the muted names a chart’s own legend has. Givenhidden(signal)(orhidden_controlled,on_hidden_change), an item is pressed to hide its series and faded while it is hidden, the arrows go between the items, and each is acheckboxto tooling. ChartLegendItem::value(text): what an item says after its name, mono 11 inMutedForeground(a slice’s share); tooling reads it with the name.orientation(Orientation::Vertical): the items one under another, each as wide as the legend, its name inCardForegroundtaking the room and its value at the end, as the board’s pie has them;size(ChartSize)gives them 8 apart and names of 13 inMd, 7 and 12 inSm.- Parts:
ChartLegendPart::Root,Item,Key,Label,Value. States:ChartLegendState::Dot,Pressable,Hidden,Vertical.
Chart Tooltip
Section titled “Chart Tooltip”The board’s Chart Tooltip: what a point is over a row for each series, its dot, its name and its value. A chart shows it at the point under the pointer or the focus; it stands on its own too.
use lurq::{app::theme::PaletteColor, ui::{ChartTooltip, ChartTooltipRow}};
ChartTooltip::new("Build 0.59") .row(ChartTooltipRow::new(PaletteColor::Chart1, "wgpu", "6.9 ms")) .row(ChartTooltipRow::new(PaletteColor::Chart2, "DirectX 12", "9.4 ms"))- A panel at least 140 wide on
Popoverwith an edge of 1, the medium radius and shadow, padded 8 and 10 with 6 between rows; the title 12/600 inPopoverForeground; a row a dot of 7, the name 11 inMutedForeground(cut with an ellipsis where it is long, the value keeping its room), the value mono 11. A chart’s tooltip stands over its point, under it where the plot has no room above, and inside the plot at its ends. - Parts:
ChartTooltipPart::Panel,Title,Row,Key,Label,Value.
Bar Chart
Section titled “Bar Chart”A value for each category, as a bar from zero: the frame time of each release, the budget of a frame by phase.
use lurq::ui::{BarChart, ChartSeries};
BarChart::new( ["0.55", "0.56", "0.57", "0.58", "0.59", "0.60"], [ChartSeries::new("Frame time", [11.8, 13.2, 9.6, 8.4, 7.0, 5.2])],).title("Frame time").description("Median per build, last six releases").current(5).value_text(|ms| format!("{ms} ms")).mount(ctx)| Builder | |
|---|---|
BarChart::new(categories, series) | The names under the bars, and the series, a value for each category |
stacked(bool) | The series one on another in each category, the first at the bottom: side by side unless told |
current(usize) | The category that is current (the latest release): its bars in their colors, the others in Input |
orientation(Orientation) | Bars standing up from the bottom (Vertical, the board’s), or lying across from the start (Horizontal): the names of the categories at the start, each at its bar’s height and at most 160 wide, the ticks’ numbers under the plot. Long names read better across |
title, description, label, size, height, legend, hidden, hidden_controlled, on_hidden_change, value_text, grid, value_axis, empty_text, loading, motion, on_select, state, style, rules, force, id, key | As every chart has them |
mount(ctx) | The tooltip of the bar under the pointer or the focus, the arrows between categories and series, on_select told a press. Converted into an element it is the still chart |
- The board’s Bar Chart (
Sk5h8): the chart’s frame atMd, bars 12 apart sharing the plot’s width, their tops rounded 4, on the line of the plot’s bottom inBorder; the names under them mono 11 inMutedForeground, each under its bar. Several series stand side by side in a category, 4 apart, and the legend under the plot names them in dots. Stacked (jJ85X), they stand one on another with a pixel of the card between segments and the top of each stack rounded, 14 between stacks. A value under zero goes down from zero, its bottom rounded, and zero is a line across the plot. The band behind the category under the pointer or the focus is inMuted. - Its motion: the bars grow from the line of zero as the chart is first shown (from its start, lying across), and move from where they were to their new place when the data changes; the bars of a series shown again grow, and those of one hidden shrink away.
- To tooling each bar is an item of the plot:
bar-<series>-<category>, named by its category, valued asvalue_textwrites it. - Parts: the chart’s (
ChartPart::Root,Header,Title,Description,Plot,Grid,Baseline,Cursor,Axis,AxisLabel,ValueLabel,Empty) andBarChartPart::Bar(the bars that give way to the current one),Band. States:ChartState::Header,Empty,Loading,BarChartState::Stacked,Horizontal,Vertical; sizesChartSize::Sm,Md. - Where the board draws nothing: the tooltip of a bar is the board’s Chart Tooltip over it; the band behind the category under the pointer; the ring of the focus around the plot; values under zero; the grid and the ticks’ numbers, off unless told.
Line Chart
Section titled “Line Chart”A value for each category joined by a line, of one series or several: the frame time of each build on two backends.
use lurq::ui::{ChartSeries, LineChart, LineCurve};
LineChart::new( ["0.54", "0.55", "0.56", "0.57", "0.58", "0.59", "0.60"], [ ChartSeries::new("wgpu", [10.4, 9.6, 9.9, 8.2, 8.6, 6.9, 6.3]), ChartSeries::new("DirectX 12", [11.6, 11.2, 10.3, 10.6, 9.4, 9.4, 8.6]), ],).title("Frame time").description("Milliseconds per frame, last 7 builds").value_text(|ms| format!("{ms} ms")).mount(ctx)| Builder | |
|---|---|
LineChart::new(categories, series) | The names of the places along the plot, the first at its start and the last at its end, and the series, a value for each; a value that is not a finite number leaves a gap in its line |
curve(LineCurve) | Straight, as the board draws it, or Smooth: a monotone curve through every value that never goes past the values beside it |
axis_labels(texts) | The texts under the plot, spread from its start to its end, in place of the categories’ names; of more than eight categories eight are written |
title, description, label, size, height, legend, hidden, hidden_controlled, on_hidden_change, value_text, grid, value_axis, empty_text, loading, motion, on_select, state, style, rules, force, id, key | As every chart has them; size is Sm and grid on unless told, as the board draws it |
mount(ctx) | The cursor, the marks and the tooltip of the place under the pointer or the focus, the arrows, on_select told a press. Converted into an element it is the still chart |
- The board’s Line Chart (
ufn5w): the chart’s frame atSm, a plot of 140 with its lines across at the ticks, lines 2 wide with round joins and ends in the series’ colors, the first drawn over the others, the names under the plot from its start to its end, and the legend in dots. At the place under the pointer: a line of 1 inInputacross the plot (the frame’sChartPart::Cursor), a mark of 10 on each line in its color ringed 2 inCard, and the Chart Tooltip with every series’ value there, 10 before the cursor and 4 from the plot’s top (after it where there is no room before it). - The pointer finds its place at once whatever the number of values (they are evenly apart), and the series whose value there is nearest it. A line of ten thousand values is one path, with no mark of its own for each.
- Left and Right go along the categories, Up and Down between the series, Home and End to the ends; the focused place shows what a hovered one shows.
- To tooling each value is an item of the plot:
point-<series>-<index>, named by its category (and its series where there are several), valued asvalue_textwrites it. - Parts: the chart’s, and
LineChartPart::Line(its opacity),Area,Point(the color of a mark’s ring). States:LineChartState::Smooth,Stacked. - Where the board draws nothing: a smooth curve, gaps, more series, values under zero (zero is a line across the plot), one value (a dot in the plot’s middle).
- Its motion: a line is drawn on from its start as the chart is first shown. When the data changes each value moves from where it was drawn to its new place, the line and its curve with it; a value added at the end comes out of the last one before, and one removed goes into the last one left, so the others only slide to their new place; a series shown again rises from the line of zero, and one hidden sinks to it. A gap the data has now is one at once.
Area Chart
Section titled “Area Chart”A line chart with the fill under each line: memory over a session, or a whole and its parts stacked.
use lurq::ui::{AreaChart, ChartSeries};
AreaChart::new( ["0", "5", "10", "15", "20", "25", "30", "35"], [ChartSeries::new("Resident", [380.0, 520.0, 470.0, 720.0, 670.0, 920.0, 870.0, 1060.0])],).title("Memory").description("Megabytes resident during a session").axis_labels(["0 min", "10", "20", "30", "40"]).mount(ctx)| Builder | |
|---|---|
AreaChart::new(categories, series), curve, axis_labels | As a line chart’s |
stacked(bool) | The areas one on another, the first at the bottom, each from the line of the one under it: overlaid unless told. A stacked series’ missing value counts as none |
| everything else | As every chart has it, with the line chart’s cursor, tooltip and keys |
- The board’s Area Chart (
yTmhJ): a line chart whose lines have the fill under them, down to zero, in the series’ colors at 0.16 (LineChartPart::Area), the line over it. Its parts and states are the line chart’s. - Where the board draws nothing: stacked areas, several series, the tooltip and the keys (the line chart’s).
- Its motion is the line chart’s, the fill moving with its line: in a stack each band’s bottom moves with the series under it, a series shown again rises from the one under it, and one hidden sinks onto it.
Scatter Chart
Section titled “Scatter Chart”Points by an x and a y on two value axes: how the frame time of a scene grows with its nodes, and what stands apart from the trend.
use lurq::ui::{ChartSeries, ScatterChart};
ScatterChart::new([ ChartSeries::points("Scenes", [(550.0, 3.3), (1600.0, 4.3), (3200.0, 8.4), (5000.0, 11.0), (7300.0, 15.5)]), ChartSeries::points("Outlier", [(1850.0, 7.6), (6150.0, 14.2)]),]).title("Nodes vs frame time").description("One dot per scene").trend(true).x_text(|nodes| format!("{}k", nodes / 1000.0)).mount(ctx)| Builder | |
|---|---|
ScatterChart::new(series) | Series of points (ChartSeries::points), each an x and a y, in any order |
trend(bool) | The straight line that fits the first series shown best (by least squares), from its least x to its most, over the points |
x_text(Fn(f64) -> String) | How a number across is written, under the plot and as a tooltip’s title: value_text’s unless told |
| everything else | As every chart has it; size is Sm, grid on and legend off unless told, as the board draws it |
- The board’s Scatter Chart (
s9y62): the chart’s frame atSm, a plot of 140 with its lines across at the ticks of the value up, the numbers of the value across under it from its start to its end (both scales start and end on round ticks), dots of 8 in the series’ colors at 0.85, and the trend 1 wide inMutedForegroundat 0.6 over them. The point under the pointer is a dot of 10 ringed 2 inCard. - The pointer finds the point nearest it in two dimensions, within 24. Left and Right go along a series in the order of its x, Up and Down between the series.
- To tooling each point is an item of the plot:
point-<series>-<index>, named by its series and its x, valued asvalue_textwrites its y. - Parts: the chart’s, and
ScatterChartPart::Point(its opacity),Ring,Trend. States:ScatterChartState::Trend. - Where the board draws nothing: the tooltip (the board’s Chart Tooltip over the point, its x as its title), the ring of the point under the pointer, a legend (off unless told), values under zero, several series.
- Its motion: the points grow in at their place as the chart is first shown. When the data changes each point moves from where it was drawn to its new place (a point is the one of its series at its place by x), and the trend with them; a point that is new grows at its place and one no longer there shrinks away at its old one, as do the points of a series shown or hidden; a trend that comes or goes fades.
Pie Chart
Section titled “Pie Chart”The parts of a whole as slices of a disc, or of a ring: the crates by size, the phases of a frame. The legend beside it names each slice and writes its share.
use lurq::ui::{ChartSeries, PieChart};
PieChart::new( ["render", "layout", "text", "other"], ChartSeries::new("Size", [4.2, 2.8, 1.9, 1.1]),).title("Crates by size").description("Share of compiled code").value_text(|mb| format!("{mb} MB")).mount(ctx)| Builder | |
|---|---|
PieChart::new(names, series) | The slices’ names, and one series with a value for each, from the top and clockwise |
donut(bool) | A ring with a hole of 0.66 of its radius, the board’s Donut Chart, Md unless told a size; a pie, Sm, unless told |
total_text(&str) | The words a donut writes in its hole under the total of the slices shown (written with value_text); nothing in the hole unless told |
colors(..) | Each slice’s color, a role or a color, in place of Chart1 to Chart5 in turn |
legend_value(PieLegendValue) | What each item of the legend writes after the name: Share (unless told), Value, None |
share_text(|share| ..) | How a share from 0 to 1 is written in the legend and to tooling: a whole percent, <1% for a sliver, unless told |
title, description, label, size, height, legend, hidden, hidden_controlled, on_hidden_change, value_text, empty_text, loading, on_select, state, style, rules, force, id, key | As every chart has them; height is the pie’s side, hidden the slices hidden by name, legend on unless told |
mount(ctx) | The slice under the pointer or the focus picked out with its tooltip, the arrows round the slices, on_select told a press (ChartPoint { series: 0, index }). Converted into an element it is the still chart |
- The board’s Pie Chart (
dDHPj): the chart’s frame atSm, a pie of 96 from the top and clockwise, a line of 1.5 ofCardon each side of the line between two slices; the legend beside it, 18 away, its items 7 apart, each a dot of 8, the name 12 inCardForegroundand the share mono 11 inMutedForegroundat its end. The Donut Chart (GJ5Mg):Md, a ring of 96 with a hole of 0.66 and no lines between slices, the legend 20 away with names of 13 and items 8 apart. - A slice hidden through the legend leaves the whole to the others, whose shares are written again. A slice too narrow at the rim to keep its color between two lines joins its neighbour without one, and is still in the legend (
<1%), the tooltip, the keys and to tooling; one slice is the whole disc; a value under zero or not a number is no slice; all zero is no data (empty_text). - Motion: the slices sweep in from the top, clockwise, as the pie first shows; on a change each slice’s ends move from where they were to where they are, so a slice hidden through the legend closes and the others take its room, and one shown again opens. Off where motion is reduced or the chart is told
motion(false), ended by a resize, nothing drawn at rest. - To tooling each slice is an item of the plot at its middle:
slice-<index>, named by its slice, valued asvalue_textwrites it with its share. - Parts: the chart’s and
PieChartPart::Slice(a slice that gives way to the one under the pointer or the focus: its opacity, 0.45),Edge(the line between slices,Card),Total(15/600 inCardForeground),TotalLabel(mono 10 inMutedForeground). States: the chart’s andPieChartState::Donut. - Where the board draws nothing: the slice under the pointer or the focus picked out by the others giving way to it, with the board’s Chart Tooltip at its middle titled by the series; the total in a donut’s hole; the ring of the focus around the plot.
Radar Chart
Section titled “Radar Chart”A value for each of several axes round a center, a polygon for each series: the profile of a renderer, the strengths of two backends side by side.
use lurq::ui::{ChartSeries, RadarChart};
RadarChart::new( ["Draw", "Text", "Layout", "Memory", "Startup", "Input"], [ ChartSeries::new("wgpu", [92.0, 70.0, 64.0, 58.0, 75.0, 66.0]), ChartSeries::new("DX12", [68.0, 76.0, 70.0, 80.0, 62.0, 86.0]), ],).title("Renderer profile").description("Relative score per area").mount(ctx)| Builder | |
|---|---|
RadarChart::new(axes, series) | The axes’ names, the first at the top and the others clockwise, and the series, a value for each axis |
value_axis(bool) | The rings’ numbers beside the first axis, each under its ring; off unless told |
title, description, label, size, height, legend, hidden, hidden_controlled, on_hidden_change, value_text, empty_text, loading, on_select, state, style, rules, force, id, key | As every chart has them; height is the square’s side |
mount(ctx) | The series and the axis under the pointer or the focus picked out with the tooltip of every series’ value on that axis; Left and Right round the axes, Up and Down between the series, on_select told a press (ChartPoint { series, index: axis }). Converted into an element it is the still chart |
- The board’s Radar Chart (
cokgK): the chart’s frame atSm, the plot a square of 150 (180 inMd) in the middle of the frame; the outer ring 15 inside the square, the rings at the scale’s round ticks (from zero, or the least value under it, to a round number at or over the most, about three) and the spokes, 1 inBorder, polygons through the axes (circles where there are fewer than three axes); each series’ area and its edge of 1.5 in its color at 0.2; the legend under the plot in dots where there is more than one series. - The axes’ names, mono 11 in
MutedForeground, stand 6 outside the outer ring, away from the center: over the top axis, before a left one, after a right one. - The pointer finds the axis nearest its direction and on it the series whose value is nearest; that series’ area is at 0.35 with its edge in its full color and drawn over the others, its point a dot of 3.5 ringed in
Card, the axis’s spoke inInput. - A missing value (not a number) stands at the center, and has no point to tooling or in the tooltip.
- Motion: the polygons grow from the center as the chart first shows; on a change each corner moves from where it was to its new value (on the scale it was on, to the one it is on), a series shown again grows from the center and one hidden shrinks to it. Off where motion is reduced or the chart is told
motion(false), ended by a resize. - To tooling each value is an item of the plot:
point-<series>-<axis>, named by its axis and its series, valued asvalue_textwrites it. - Parts: the chart’s and
RadarChartPart::Ring(the rings and the spokes),Area(a series’ opacity),ActiveArea(the opacity of the series under the pointer or the focus). - Where the board draws nothing: the axes’ names (the board has none, and the square is in the middle of the frame so that they have room on both sides); the picked-out series and axis with the board’s Chart Tooltip; the rings’ numbers, off unless told; the ring of the focus around the plot.
Heatmap
Section titled “Heatmap”A grid of cells, a row for each series and a column for each category, each colored by its value’s step on a scale: commits per day, temperature by hour.
use lurq::ui::{ChartSeries, Heatmap};
Heatmap::new( weeks, // the columns' names ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"].map(|day| ChartSeries::new(day, commits_on(day))),).title("Commits").description("Per day, last 18 weeks").mount(ctx)| Builder | |
|---|---|
Heatmap::new(columns, rows) | The columns’ names, and the rows, each a series with a value for each column |
steps(usize) | How many steps the scale has, two at least: five unless told, the board’s |
range(least, most) | The values the scale runs between: zero (or the least value, where one is under zero) to the most unless told |
cell_size(f32) | A cell’s side: 14 unless told; smaller where the grid is wider than the frame |
column_axis(bool) | The columns’ names under the grid, as many as have room; off unless told, as the board’s |
less_text, more_text | The scale’s words at its ends: “Less” and “More” unless told |
missing_text | What the tooltip and tooling say of a cell with no value: “No value” unless told |
title, description, label, size, height, legend, value_text, empty_text, loading, on_select, state, style, rules, force, id, key | As every chart has them; height makes the cells as tall as the rows can be in it, legend is the scale |
mount(ctx) | The cell under the pointer or the focus ringed with its tooltip; the arrows from cell to cell, Left and Right along a row and Up and Down along a column; on_select told a press (ChartPoint { series: row, index: column }). Converted into an element it is the still chart |
- The board’s Heatmap (
rSu67): the chart’s frame atSm; the rows’ names mono 10 inMutedForegroundat the plot’s start, every other one where more than four rows are as close as the board’s; cells of 14 with corners of 3, 4 apart; the scale under the grid at the frame’s end, its words mono 11 inMutedForeground6 from its steps of 12 with corners of 3 (FGewe). - The scale’s steps are measured from the board: a value at or under the scale’s least is in
Muted; the others areChart1at a quarter, a half, three quarters and the whole of its opacity (with five steps), drawn over the card. A value’s step is as high as its share of the range, rounded up, so that any value over the least shows. A cell and the scale’s step of its value are drawn in one color, so a cell is the scale’s color at its value. - A cell with no value (not a number) is an edge of 1 in
Border; the tooltip and tooling saymissing_text. A grid wider than the frame has smaller cells, its gaps as much smaller, and the plot is as high as the cells are drawn at its width, laid out again as the width changes (the rows’ names fewer where they would crowd). - Motion: the cells fade in as the heatmap first shows; on a change each cell goes from its old step’s color to its new one, a cell that comes fading in and one that goes fading out. Off where motion is reduced or the chart is told
motion(false), ended by a resize. - To tooling each cell is an item of the plot:
cell-<row>-<column>, named by its row and its column, valued asvalue_textwrites it. The scale is animgnamed from its two words. - Parts: the chart’s and
HeatmapPart::Cell(the lowest step,Muted),Fill(the highest,Chart1),Missing,Ring(round the cell under the pointer or the focus, 1.5 inForeground),Scale,Step,ScaleLabel. - Where the board draws nothing: the tooltip of a cell, its key in the cell’s color; the ring of the cell under the pointer or the focus; the columns’ names, off unless told; a cell with no value. The board names Mon, Wed and Fri of its seven days; the heatmap names every other row from the first, so Sun as well.
Data Grid
Section titled “Data Grid”A table whose cells are worked in: the focus is on a cell, the arrows move it from cell to cell, and a cell is edited in place with the system’s own controls. A list of files whose names are edited, a sheet of orders whose states are chosen.
use lurq::ui::{CellEditor, CellValue, DataGrid, TableColumn};
// files: Signal<Vec<File>>, the app's rowslet columns = vec![ TableColumn::new("name", "Name").text(|row: &File| row.name.clone()).editor(CellEditor::text(|row: &File| row.name.clone())), TableColumn::new("kind", "Kind").width(120.0).text(|row: &File| KINDS[row.kind].into()).editor(CellEditor::choice(KINDS, |row: &File| row.kind)), TableColumn::new("size", "Size").width(90.0).numeric().text(|row: &File| format!("{} KB", row.size)).editor(CellEditor::number(|row: &File| row.size)), TableColumn::new("shared", "Shared").width(80.0).editor(CellEditor::checkbox(|row: &File| row.shared)),];let store = files.clone();DataGrid::new(columns, files.get()) .row_key(|row: &File| row.name.clone()) .label("Files") .selected(selected) .height(320.0) .on_edit(move |edit| { let mut files = store.get(); let Some(file) = files.iter_mut().find(|file| &file.name == edit.row) else { return false }; match (edit.column, &edit.value) { ("name", CellValue::Text(name)) if name.is_empty() => return false, // refused: the editor stays open ("name", CellValue::Text(name)) => file.name = name.clone(), ("kind", CellValue::Choice(kind)) => file.kind = *kind, ("size", CellValue::Number(size)) => file.size = *size, ("shared", CellValue::Checked(shared)) => file.shared = *shared, _ => return false, } store.set(files); true }) .mount(ctx);| Builder | |
|---|---|
DataGrid::new(columns, rows), new_shared(columns, Arc<Vec<R>>), row_key(|row| K) | A table’s columns and rows, and what tells a row apart |
TableColumn::editor(CellEditor) | How the column’s cells are edited: CellEditor::text(|row| String) (an Input), number(|row| f64) (a NumberInput), choice(choices, |row| usize) (a Select of the choices), checkbox(|row| bool) (a box ticked in the cell, which a column that builds no cell of its own shows). A column with none is read |
on_edit(|edit: &CellEdit<K>| bool) | Told each edit committed: edit.row (the row’s key), edit.column (the column’s id), edit.value (a CellValue: Text, Number, Choice, Checked, or Empty for a number or a choice cleared). It returns whether the app takes it; every handler is told, and one refusing it refuses it. A paste and Delete come here a cell at a time |
column_layout(Signal<ColumnLayout>), column_layout_controlled(layout, |layout| ..), on_column_layout_change(|layout: &ColumnLayout| ..) | How the columns are arranged, the grid’s own unless the app holds it: layout.columns, a ColumnPlace for each in the order shown (id, hidden, width where a person made it, fit where it is as wide as its content, pin). The grid tells the whole of it at each change, so an app that stores it gives back what a person left; a column it does not name is as the app made it, after the others |
column_menu(bool) | A menu on each header: on unless told |
row_numbers(bool) | A column of the rows’ numbers at the start: off unless told |
TableColumn::filter_text(bool), filter_set(bool), filter_values(|row| String), filter_number(|row| f64), filter_date(|row| Option<Date>), filter_bool(|row| bool) | How a column is filtered: by its text (contains, starts with, equals), by the values ticked among those it has (its text, or what filter_values gives a column whose cell is an element), by a number or a day (a range, or a comparison), by a yes or no |
filters(Signal<TableFilters>), filters_controlled(filters, |filters| ..), on_filters_change(|filters: &TableFilters| ..) | The filters, the grid’s own unless the app holds it: a person sets them from the column’s menu and the filter row |
filter_row(bool), filter_labels(FilterLabels) | A row of filters under the header: off unless told; and every word of filtering |
search(Signal<String>), search_controlled(query, |query| ..), on_search_change(|query: &str| ..), search_options(FindOptions), on_matches_change(|matches: SearchMatches| ..) | What is searched for in the cells, every match marked; how the query matches; told how many matches there are and which is current |
DataGrid::on_demand(columns, total, |request: GridRequest| async { .. }), on_query_change(|query: &GridQuery| ..), source_labels(SourceLabels) | A grid over rows the app gives on demand: see below |
tree(|row| Option<K>), expanded(Signal<Vec<K>>), expanded_controlled(open, |open| ..), on_expanded_change(|key, open| ..) | The rows as a tree, each under the row whose key its parent is; the rows open, the grid’s own unless the app holds them (every row closed at first) |
detail(|row| Element), details(Signal<Vec<K>>), details_controlled(open, |open| ..), on_detail_change(|key, open| ..) | What a row shows under it while it is open; the rows whose detail is open, the grid’s own unless the app holds them |
toolbar(bool), toolbar_labels(GridBarLabels) | The bar of the grid’s tools over it, off unless told: see below; and its words (GridBarLabels { bar, search, filter, columns, export, density, comfortable, default, compact }) |
export(bool), on_export(|export: &GridExport| ..), export_labels(ExportLabels) | Export in each column’s menu: the rows shown or selected written out as CSV or tab-separated text, on unless told; told the text (GridExport { format, scope, text, rows }), which goes on the clipboard where no one is told; and its words. to_csv(&columns, &rows), to_tsv and to_delimited(&columns, &rows, ExportFormat) write any rows in a grid’s columns, the grid or not |
find_bar(bool), find_bar_with(|bar: FindBar| bar) | Ctrl+F opens a find bar over the grid: off unless told; and what the bar is made of besides its query and its count (its words) |
column_menu_labels(ColumnMenuLabels), menu_trigger_label(|title| String), group_label(|title, value, count| String), summary_labels(SummaryLabels), row_numbers_label(&str) | The words the grid writes, each said otherwise: the column menu’s items (ColumnMenuLabels { sort_ascending, sort_descending, clear_sort, pin_start, pin_end, unpin, size_to_fit, hide, columns, show_all }, English by ..ColumnMenuLabels::default()), the name of a menu’s trigger (“Name column menu”), of a group’s row (“Status: Passing, 3 rows”), the summary’s words (SummaryLabels { sum, average, count, min, max, row }) and the numbers’ mark (”#“) |
TableColumn::summary(SummaryKind), TableColumn::summary_text(|rows: &[&R]| String) | What a column says in the summary rows: SummaryKind::Sum, Average, Count, Min, Max, which the grid computes from the values the column’s editor edits or the numbers its text starts with (“12 KB”), a count of any column; or the app’s text of the rows summed up. A grid with a column that says one has a summary row |
group_by(["status", ..]), open(Signal<Vec<GroupKey>>), open_controlled(open, |open| ..), on_open_change(|key: &GroupKey, open| ..) | The rows grouped by the values of these columns (a column grouped by may be hidden), and the groups open, the grid’s own unless the app holds them (every group closed at first). A GroupKey is the values from the first column grouped by to the group’s own: GroupKey::new(["Passing"]), GroupKey::new(["Passing", "Ada"]) |
cell_selection(Signal<Option<CellRange<K>>>), cell_selection_controlled(range, |range| ..), on_cell_selection_change(|range: Option<&CellRange<K>>| ..) | The range of cells selected, the grid’s own unless the app holds it: range.anchor and range.extent its corners (a CellKey: row, the row’s key, and column, the column’s id), range.rows and range.columns the keys and the ids it spans in the order shown. CellRange::new(anchor, extent) makes one to give the grid |
read_only(bool) | No cell is edited: the cells take the focus and are read |
resizable(bool) | Columns made wider or narrower by a person: on unless told |
mount(ctx) | The grid that works: its cells take the focus and are edited, and it builds the rows and the columns in view. Converted into an element it is the still form of itself, read and selected as a table |
sort, sort_controlled, on_sort_change, selected, selected_controlled, on_selection_change, checkboxes, on_row_click, on_row_activate, on_column_resize, on_column_resize_end, density, height, max_height, empty, empty_text, loading, loading_rows, pagination, count, total, count_text, select_all_label, select_row_label, resize_label, label, disabled, state, style, rules, force, id, key | As a table has them. A cell’s id is the grid’s with -cell-, its row and its column (files-cell-2-0); the editor’s is the grid’s with -editor |
- The grid is one stop of Tab after its header (whose sortable and resizable headers are a stop of their own), at the cell that last had the focus or the first cell of the first selected row. Left and Right move along the row, Up and Down to the same column of the row before and after, Home and End to the row’s first and last cell, Ctrl+Home and Ctrl+End to the first cell of the first row and the last of the last, PageUp and PageDown by what the grid’s height shows; a row or a column that is not built is scrolled to, built and focused. Tab goes on to the next cell of the row, Shift+Tab to the one before, and out of the grid from the row’s last and first. Space selects the row (with Shift from the last selected one), Enter on a cell that is not edited activates its row, as a double press of it does. A press of a cell focuses it and does not select its row: the rows are selected with their checkboxes and Space.
- Filters: a column says how it is filtered (
TableColumn::filter_textand the others), and its menu has “Filter…”, which opens a panel under its header (a choice of contains, starts with or equals and a box for a text; the values the column has, each ticked, with “Select all” and “Select none”, at most 500 of them; boxes of at least and at most for a number, of from and to for a day; a choice of all, yes or no), “Clear filter” and “Clear all filters”. A change applies as it is made. Withfilter_row(true)a row under the header, which stays with it, has a filter in the cell of each column that filters: a box for a text (contains), for a number or a day (>10,<=5,5..20,=7or one value;>and<are taken as at least and at most), a choice of a value or of yes and no. A filtered column’s header has the funnel after its title (TablePart::FilterIcon,icons::FILTER). The grid shows the rows every filter lets through, in their order: grouped, the groups are of those, and a summary is of them; the count reads “12 of 340 rows”.TableFiltersis the app’s value (with,without,get,iter,valid(ids)), its textfilter("name" contains "lurq") filter("size" at_least:10) filter("status" in "Passing" "Failed") filter("updated" from:2026-01-01 to:2026-02-01) filter("shared" is:true)(to_text,parse,Display,FromStr) and, withpersistent_storage, a value of the storage. A filter is aColumnFilter:Text { how: TextMatch, text },Number { at_least, at_most },Date { from, to },Set(values),Bool(value). Parts:TablePart::FilterRow(44 high onBackground, a line under it),FilterLabel(the panel’s words over its boxes, 12 inMutedForeground). - Rows on demand, as a server’s table gives them:
DataGrid::on_demand(columns, total, fetch)is told how many rows there are at first and asksfetchfor the ranges of the rows built, a hundred at a time, four at once, through the engine’s futures;fetchanswers now or later with aGridPage { rows, total }(the rows of the range, fewer at the end, and how many there are as the query has them) or anErr(message). A row whose range has not come is a skeleton; a range that failed says so in each of its rows, with a Retry (SourceLabels). The rows areSourceRow<R>, each its row where it has come (get()), told apart by their place. The sort, the filters and the search are the app’s: eachGridRequestcarries them as oneGridQuery { sort, filters, search }, another of them asks for every range again, andon_query_changeis told it as a person changes one.GridQueryhas a text form,sort("size" descending) filter("status" in "Failed") search("canvas")(to_text,parse,Display,FromStr), and is a value of the storage. Over a source the cells are not edited and the rows are not grouped or summed, and the grid does not search: the app does. At most 200 ranges are kept; those far from the view go first. - Search:
search(query)marks every match of the query in the text of the cells of the rows shown (a cell whose content is an element is not searched), as a find marks it (Highlight’s marks, the text’s weight kept), the current one stronger, with its edge. F3 and Shift+F3 in the grid go to the next match and the one before, round from the last to the first, across rows not built yet: each is brought into view, down and across. Withfind_bar(true)Ctrl+F (Cmd+F) opensFindBarover the grid: its query is the grid’s search (on_search_changehears it), its toggles the case and whole words, its count2 of 8, its arrows the next and the one before.on_matches_changeis toldSearchMatches { count, current }each time that changes. The matches are found once for the rows, the lines shown and the query, over every row shown: a search of a million rows of many columns takes as long as reading them. With rows the app gives on demand the app searches. - A range of cells: a drag from a cell selects the cells from it to the one under the pointer (the rows and the columns scroll where the drag goes past the view), Shift with the arrows, Home, End, PageUp and PageDown (with Ctrl, Home and End to the corners) moves the range’s other corner from the focused cell, Shift with a press takes it to the cell pressed, and Ctrl+A selects every cell. The focus stays on the cell the range started from; a move of the focus, a press without Shift and Escape end the range. It is drawn as one area: every cell of it but the focused one in
Selection, an edge of 2 inRinground it, the focused cell on its row’s fill; each of its cells isa11y_selectedto what reads the tree. It is apart from the rows’ selection. It names its cells by the rows’ keys and the columns’ ids, so the same cells stay in it when the app sorts the rows. - A column’s menu: a button of 24 at the end of each header, its mark in
MutedForeground, shown while the pointer is on the header or the focus is in it and while the menu is open; Alt+Down on the header (or the menu key, or Shift+F10) opens it too. The menu is aui::Menuunder the button: Sort ascending, Sort descending and Clear sort for a sortable column, Pin to start, Pin to end and Unpin, Size to fit, Hide column (not the last one shown), and Columns, a menu of every column checked where it is shown, with Show all columns. A choice of the sort sets the grid’s sort as a press of the header does; the others change the arrangement of the columns. - A header dragged to another place moves its column there: a line of 2 in
Ringat the start of the header it goes before, or the end of the last. Ctrl+Shift+PageUp and PageDown on a header move its column a place back or on, as a browser moves a tab. A column pinned at the start stays among those at the start, one at the end among those at the end. A resize is kept in the arrangement too, as the column’swidth. - Group rows: a row for each value of the first column grouped by, in the order its first row is, with a chevron (right closed, down open), the value 13/500 in
Foregroundand how many rows it holds mono 12 inMutedForeground, onMuted, as high as a row; in it, a group for each value of the next column, indented 20 a level, then its rows. What it says stays at the start while the rows scroll sideways. A press of it, Enter or Space on it opens or closes it; the rows are a nested list, so Right opens a group and Left closes it, and Left on a row in it goes to the group. The rows of a closed group are not built, and the window of rows in view counts the groups’ rows with the rows: ten thousand rows in three groups build a screen of them. To what reads the tree a group’s row is arowwitha11y_levelanda11y_expanded, named by its column, its value and its count. A group’s row is the grid’s with-group-and its line (files-group-0). - Row numbers: a column at the start, before the checkboxes, that stays while the columns scroll sideways, with each row’s number among the rows shown, from 1, mono 12 in
MutedForegroundat its end (the selected row’s inForeground), as wide as the widest number. Where the rows are selected, a number is pressed to select its row alone, with Ctrl to add it or take it out, with Shift the rows from the last selected one, as a press of a table’s row does; the column’s header, a#, selects every row, or none where all are. To what reads the tree a number is arowheader. A number’s id is its row’s with-number, the header’s the grid’s with-numbers. - Storing what a person did: the arrangement of the columns, the sort, the filters (
TableFilters, above) and the groups open are the app’s values, each stored as text, as a dock’s state is.layout.to_text()(andDisplay) writes the arrangement,column("size" width:150) column("name" pin:start) column("status" hidden), andColumnLayout::parse(&text)(andFromStr) reads it back to an equal value, orNonefor text that is not the form;layout.valid(ids)brings it to the columns the app has now (one it no longer has out, a new one at its place after the one before it), which the grid also does as it shows it. A sort is"status" ascending "size" descending, its columns in turn (TableSort::list_to_text,TableSort::parse_list; one column aloneTableSort::to_text,TableSort::parse), a groupgroup("Passing" "Ada")(GroupKey::to_text,GroupKey::parse), the groups open their list (GroupKey::list_to_text,GroupKey::parse_list);TableTextErroris whatFromStrreturns for text that is not the form. With thepersistent_storagefeature each is a value of the app’s storage, stored as that text:ctx.set_persistent_value("columns", layout.get()),ctx.set_persistent_value("sort", sort.get())(aVec<TableSort>, none as no text),ctx.set_persistent_value("open", open.get())(aVec<GroupKey>), andctx.persistent_value::<ColumnLayout>("columns")reads one back. - Summary rows: where a column says a summary, the grid has a row at its bottom that stays there while the rows scroll, over what scrolls under it, with what each column says of every row, and each group open ends in a row with what it says of the group’s rows. A summary row is as high as a row, on
Mutedwith a line of 1 over it; a cell says its kind 12 inMutedForeground(“Sum”) and its value 13/500 inForeground, at the column’s side; a cell of a column that says none is empty. The bars run above the grid’s summary. A summary row is not a stop: the keys pass it by. A mounted grid computes what its summaries say when what they are computed from changes (the rows the app gives, the columns’ summaries, the grouping), every open group’s at once, and keeps it: a scroll, the pointer and the focus compute nothing. Its id is the grid’s with-summary, a group’s-summary-and its line. - Ctrl+C copies the range, or the focused cell, as tab-separated text, a line for each row: the value a cell’s editor edits (a number as it is, a choice by its name, a box
trueorfalse), or its column’s text. Ctrl+V pastes tab-separated text from the range’s first cell, or the focused one: each cell that is edited and would change is told toon_edit, which may refuse it, a number read as one, a choice by its name, a box bytrue,yes,1orx; one value pasted into a range fills it. Delete clears what is edited of the range: a text to nothing, a box unticked, a number and a choice toldCellValue::Empty. Ctrl+X copies and clears. All of it reaches the rows not built too: Ctrl+A and Ctrl+C on ten thousand rows copy ten thousand lines. Through the engine’s clipboard (copy events), which a test installs its own of. - A cell is edited with its column’s editor: Enter or F2 on it, a double press of it, or a letter or a digit typed on it, which the edit starts from. Enter commits and goes to the cell under it, Tab commits and goes on to the next cell, Shift+Tab to the one before, Escape puts the cell back as it was and gives it the focus again. A choice commits as it is chosen; a box turns at a press or Space, with no editor. An edit the app refuses leaves the editor open with its value, marked
invalid, and the focus in it. The focus moving to another cell commits what was typed, and closes the editor however the app answers. - Tree rows: with
tree(|row| parent)each row comes after the row whose key its parent is, the rows under one in the order the app gives them (its sort’s), a row whose parent is not among the rows at the top. The first column’s cell is indented 18 a level and starts with the chevron (TablePart::TreeToggle, 14,MutedForeground,Foregroundunder the pointer; right closed, down open), 6 before its content, or with the chevron’s room where no row is under it, as the board’s Tree table draws it. A press of the chevron opens or closes the row and does nothing else; Right on the first cell opens a closed row, Left closes an open one, and Left on a closed row, or one with nothing under it, goes to the row it is under. A filter keeps the rows a row it keeps is under. The rows of a closed row are not lines: they are not built, and ten thousand rows in a few open folders build a screen of them. To what reads the tree a row hasa11y_levelfrom 1 and, where rows are under it,a11y_expanded; the body is a nested list, as a grouped grid’s. A grid grouped by columns is no tree. - A row’s detail: with
detail(|row| element)an open row has a line under it with the element, onMutedwith 12 down and 16 across and a row’s line under it (TablePart::Detail), as wide as the grid’s view and staying in it while the columns scroll sideways, as high as what it holds: its line is measured as it is laid out, as a row that wraps is, and the window of lines counts it. Where the rows are no tree, the first cell’s chevron opens and closes it, and Right and Left on that cell do. What is in it is reached with Tab; the arrows go from row to row past it. Its id is the grid’s with-detail-and the row’s place (files-detail-3). - The bar over the grid: with
toolbar(true)the grid has the board’s Table Toolbar over it, 8 above it, as wide as it, built from aToolbar(its surface: 52 high, padded 12 across, 8 between, the large radius): aSearchFieldof 220 (Sm) whose query is the grid’s search, the app’s (search,search_controlled, told throughon_search_change) or the grid’s own where the app holds none; aTag(Info, 26 high, 12) for each filter set, “Status: Passing”, whose × takes it off; Filter (an outline button of 26, its plus 12), a menu of the columns that filter, each opening its filter’s panel under its header; then at the end the density, aToggleGroupof three cells of 30 (icons::ROWS_2,ROWS_3,ROWS_4) showing the grid’s density until a person chooses one, which the grid then takes; Columns (an outline button of 30 with its chevron), a menu of every column checked where it is shown; and Export (an outline button of 30 withicons::DOWNLOAD), the menu of the column menus’ export. What does not fit goes into the bar’s menu, the search field last. Its ids are the grid’s with-bar,-bar-search,-bar-filter,-bar-filter-and a column’s id for a tag,-bar-density,-bar-columnsand-bar-export. - Export: a column’s menu ends in Export, a menu of Shown rows as CSV, Shown rows as tab-separated, Selected as CSV and Selected as tab-separated (the last two only where rows are selected or cells are in a range). The text’s first line is the titles of the columns shown, in their order; then a line for each row, every row the grid shows (filtered and sorted as it shows them, those not built too), or the rows selected in the order shown, or, with no row selected, the range’s rows in its columns. A cell says its column’s text as it is shown, or the value its editor edits where the column has no text (a box
trueorfalse), or nothing for a cell the app builds. CSV is RFC 4180’s: a field with a comma, a quote, a line break or a space at an end is quoted, its quotes doubled, and the lines end with CR LF; tab-separated text has a space for a tab or a line break in a field, and LF. The app is told it (on_export, aGridExport:format,scope,text,rows) to save it as a file,format.extension()andformat.media_type()saying of what kind; with no one told the text goes on the clipboard. It is written at once from every row: a million rows of two hundred columns are that much text. Over rows the app gives on demand, the rows that have not come are empty lines: the app has them, and writes them withto_csv(&columns, &rows). - The grid edits nothing of its own: the rows are the app’s, which
on_editchanges and gives again, and the grid shows them at the next render. - To what reads the tree it is a
grid, its rowsrows witha11y_rowindexanda11y_selectedwhere rows are selected, its cellsgridcells witha11y_colindex(the checkboxes’ column counted),a11y_rowindex,a11y_readonlyanda11y_selectedwhere they are in the range, its headerscolumnheaders. - In the design (
pencil/lurq-design-system.pen, Data Grid) it is the table with the column of checkboxes: 12 between columns, the checkboxes 16, the name in the mono type and sorted with its arrow, a status as a badge, a size of 12 inMutedForegroundat its end, the selected row onHighlight, a footer of 44 with the count and the pager. Where the board draws nothing: a cell focused from the keyboard has the ring of 2 inRinginside it, as a row of a table; the range of cells is the text selection’sSelectionedged inRing; a column’s menu is the system’s menu from a ghost button of 24 at the header’s end, as the board’s toolbars have them; an editor is the system’s control of the small size (32), as wide as its cell; a column’s resizer is the table’s. - Its parts and states are the table’s (
TablePart,TableState), and so is its renderer: a theme restyles a grid as it restyles a table, and aTableViewof a grid saysview.grid, eachTableCellitsgrid(aGridCell: its row, whether it is editable, whether it is in the range, its editor while it is edited, whether Tab enters at it, itsa11y_colindex). - The board’s Property Grid (two columns of a name and a control, in categories that open and close) is not a data grid: it would take its tracks and its editors’ controls from it, its categories from a tree view’s open rows, and edit every value in place at once rather than one cell at a time.
Calendar
Section titled “Calendar”The days of a month in weeks, which a person chooses a date from, or a range of dates: a due date, a day to book, the week of a report.
use lurq::{ core::{Date, DateRange, Signal, YearMonth}, ui::{Calendar, DateMemory},};
// due: Signal<Option<Date>>; in a component's render, mounted so that it keeps the month it shows.Calendar::new(due.clone()).min(Date::today()).mount(ctx);
// The month shown in a signal of the app's: it is not the value.Calendar::new(due.clone()).month(shown.clone()).mount(ctx);
// stay: Signal<Option<DateRange>>: a range with two presses, two months side by side, weekends not to be chosen.Calendar::new(stay.clone()) .months(2) .disabled_days(|date| date.weekday().days_from_monday() >= 5) .on_change(|range: DateRange| println!("{range}")) .mount(ctx);
// The app holds the date and answers a choice.Calendar::controlled(self.due.get(), move |date: Date| due.set(Some(date)));
// What it keeps, kept by the app in a field of its component, made once: for a calendar built without ctx.Calendar::new(due.clone()).memory(&self.memory);| Builder | |
|---|---|
new(Signal<Option<Date>>), new(Signal<Option<DateRange>>) | What is chosen, which a choice sets: a date (a Calendar), or a range chosen with two presses (a Calendar<DateRange>) |
controlled(Option<V>, Fn(V)) | The app’s value, and what it is told of a choice, which the calendar does not set: the app answers with the value it renders it with next |
month(Signal<YearMonth>) | The month shown, the first where there are several: not the value. The heading’s buttons and the keys set it |
memory(&DateMemory) | What the calendar keeps between renders, the app’s: the month it shows where the app gives none, a range’s first press and where it would end |
mount(ctx) | The calendar with a memory of its own |
months(n) | How many months side by side, each with its heading |
min(Date), max(Date) | The least and the greatest date that can be chosen. The months beyond are not shown |
disabled_days(Fn(Date) -> bool) | Which days cannot be chosen besides those out of the range |
locale(impl DateText), first_day(Weekday) | Its text (a DateLocale, the app’s own DateText, or an Arc of it) in place of the app’s (app.set_date_locale, English where it set none), and the first day of the week in place of the text’s |
week_numbers(bool) | The ISO 8601 week number before each week |
outside_days(bool) | The days of the months before and after in the first and the last week; on, as the design draws them, and none with several months |
today(Date) | The day marked as today (the state Current), in place of the system’s |
other_end(Option<Date>) | Of a calendar of one date: the other end of a range its date is one end of, the date of the range’s other picker, marked (the state OtherEnd, on Highlight with its radius, range_other_end to tooling) while a person chooses this end |
disabled(bool) | It takes no input |
footer(element) | An element of the app’s under the months, across the panel, in the part Footer: 8 under a line of 1 in Border. Today and Clear, a line of what the days mean. It is not in the focus group of the days |
label(&str) | What the calendar is called to tooling: its panel is then a group. Each month is a grid called by its month whatever it says |
previous_label(&str), next_label(&str) | What the buttons of the heading are called: “Previous month” and “Next month” in English |
on_change(Fn(Date)), on_change(Fn(DateRange)) | Told of another date chosen, or another range ended, with it; bound to a signal, the value is set already. Not for what is chosen already, nor for the app setting the value. A second handler is called after the first |
on_choose(Fn(Date)), on_choose(Fn(DateRange)) | Told of every choice, of what is chosen already too: what closes a picker of the app’s that holds the calendar. A second handler is called after the first |
heading(CalendarHeading) | How the headings are laid out: Centered, the month between the buttons (the default, the design’s), or MonthThenNav, the month at the start and both buttons after it at the end, 4 apart (of several months, at the end of the last month’s heading; state CalendarState::NavAtEnd) |
keys(CalendarKeys) | Where the keys are read: Days, the default, the days taking the focus; or Panel, the panel reading them wherever the app keeps the focus (see below) |
state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. force draws the day Tab would enter at. Each day has the id with -day- and the date after it: due-day-2026-11-12; a weekday’s head -weekday- and its English short name (due-weekday-mon); the buttons -nav-previous and -nav-next; its other parts - and the part’s name (see ids of parts) |
-
The calendar does not keep what is chosen: the app’s signal does. It keeps the month it shows, starting at the month of what is chosen, or of today, and follows the value to its month when the app sets it to a date that is not shown; mounted, or with a
DateMemory, it keeps it between renders. Converted into an element with neither it keeps nothing: its buttons show no other month unless the app gives it the month, and a range shows only once it is chosen. -
Its text (the title of a month, the heads of the weekdays, what a day and the buttons are called) is one
DateText: its own.locale(..), else the app’s (app.set_locale(..), whoseLocale::datesit is, orapp.set_date_locale(..)after it), else English. The app’s is read where the calendar is built in a render, mounted or not, and a change of it builds the calendar again. An app that names its months or its weekdays in words of its own changes them in the locale’sdates(months,weekdays_short,weekdays,labels, …) and sets it:let mut locale = Locale::for_tag("uk");locale.dates.weekdays_short = ["пн", "вт", "ср", "чт", "пт", "сб", "нд"].map(Arc::from);locale.dates.months[10] = Arc::from("Листопад");app.set_locale(locale); -
A range: the first press starts it, the pointer and the keys show where it would end, and the second ends it, before the first or after it. Its ends are chosen days, and the days between are one band.
-
The days are one stop of Tab, at the chosen day, today or the first of the month; the buttons of the heading are stops of their own before them. Left and Right go a day, Up and Down a week, Home and End to the ends of the week, PageUp and PageDown a month and with Shift a year: into the month before or after, which is then shown, and kept between the least and the greatest date. A day that cannot be chosen takes the focus too and says so: the keys pass no day by. Enter and Space choose. The keys are the days’ own, through the engine’s
KeyboardEvent::focus_key. -
Read at the panel (
keys(CalendarKeys::Panel)), for a picker in a popover that keeps the focus in the app’s field or panel, the days take no focus and are no group of it, and a press of one leaves the focus where it was. One day is the one the keys are on (stateCalendarState::Cursor, ringed as a focused day is,cursoron it and the date on the panel to tooling): the chosen day, else today, else the first of the month to begin with, and again after a choice and where its month is no longer shown. While the calendar is shown the panel reads the keys wherever the focus is: Left and Right move that day a day, Up and Down a week, PageUp and PageDown a month and with Shift a year, showing its month; Enter chooses it and tellson_choose, so that the picker closes. A key a handler before took (prevent_default), a key with Ctrl, Alt or Cmd, an Enter where the focus is on what takes Enter itself (a button of the footer), and Home and End, which are the field’s, are left alone. The day is kept where the month is: mounted, or in aDateMemory. -
To what reads the tree each month is a
gridcalled by its month (November 2026), ofrows ofgridcells called by their day (Thursday, Nov 12, 2026) that saya11y_selected,a11y_current(date, for today) anda11y_disabled; the names of the days arecolumnheaders. -
Parts:
CalendarPart::Root(the panel),Months(the row of headings and the row of days, its gap the room between months),Header,Title,NavandNavIcon(rules over the outline buttons and their glyphs),Grid,Weekdays,Weekday,Week,WeekNumber,Day,Footer. States of the calendar:CalendarState::Disabled,Bare(in a picker’s panel: no fill or edge of its own);NavAtEnd(the buttons at the end of the heading); of a day:Selected,Current(today),Outside,Unavailable,RangeStart,RangeEnd,InRange,OtherEnd,Cursor(the day the keys are on, read at the panel). -
In the design the panel is 248 wide, on
Popoverwith an edge of 1 inBorder,radius-lgand 12 of padding; the heading is 32 high, the month in the body’s type at 500 between two outline buttons of 28 (radius-md, edge inInput, chevrons of 16 inMutedForeground), 8 over the days. A day is 32 square withradius-md, its number at 13; the names of the days are at 12 inMutedForeground; the rows are 8 apart. Today and a day under the pointer are onHighlight(the board’saccent); the chosen day is onPrimary, its number inPrimaryForegroundat 500. A day of the month beside, and one that cannot be chosen, is inMutedForegroundat half opacity. The days between a range’s ends are onHighlightwith no radius. -
A theme’s renderer is given
CalendarView:view.months,view.chosen,view.draft,view.hover,view.shown_range(),view.day_states(date, outside),view.day_recipe(states),view.entry(), and the piecesnav(by),header(index),headers(),weekdays(),day(date, month),week(days, month),grid(index),grids(),panel()andrender().
Date Picker
Section titled “Date Picker”A field that holds a date, typed in it or chosen from a calendar that opens under it: a due date, a date of birth, the day of a booking.
use lurq::{ core::{Date, Signal}, ui::{DateMemory, DatePicker, Field},};
// due: Signal<Option<Date>>DatePicker::new(due.clone()).placeholder("Pick a date").clearable(true).mount(ctx);
// In a field, which names it and judges it; the field mounted mounts the picker.Field::new("Due date", DatePicker::new(due.clone()).min(Date::today())) .error("The due date has passed.") .mount(ctx);
// Written and read the app's way.DatePicker::new(due.clone()).format(|date| date.to_string()).parse(|text| text.parse().ok());
// The app holds the date and answers what is typed or chosen.DatePicker::controlled(self.due.get(), move |date| due.set(date));| Builder | |
|---|---|
new(Signal<Option<Date>>) | The date the field holds |
controlled(Option<Date>, Fn(Option<Date>)) | The app’s date, and what it is told of an edit or a choice, which the picker does not set: the field shows what the app holds until it answers |
memory(&DateMemory), mount(ctx) | What it keeps between renders (whether the calendar is open, the field it opens under, the month shown): the app’s, or its own where it is mounted |
open(Signal<bool>), month(Signal<YearMonth>) | Whether the calendar is open and the month it shows, where the app holds them |
placement(Placement), offset(..), collision(CollisionStrategy) | Where the calendar opens beside the field (BottomStart), how far from it, and where it goes with no room, as a popover’s |
inline(bool) | The panel drawn in place under the field, open or not, taking no focus: for a gallery, a test, a page that holds a calendar |
placeholder(&str) | What the field says while it is empty |
format(Fn(Date) -> String), parse(Fn(&str) -> Option<Date>) | How the field writes the date and reads what is typed, in place of the locale’s |
locale(impl DateText) | How dates are written and read, and the calendar’s names, first day and the controls’ names, in place of the app’s (app.set_date_locale, English where it set none) |
min, max, disabled_days, first_day, week_numbers, today | As the calendar’s: what cannot be chosen cannot be typed either |
other_end(Option<Date>) | The other end of a range the date is one end of, which the calendar marks: a start’s picker is given the end’s date, and the end’s the start’s |
clearable(bool) | A button at the end of the field that empties it while it holds a date |
size(DatePickerSize), invalid, warning, valid, read_only, disabled, label, full_width, name | As an input’s; DatePickerSize is TextBoxSize. A read-only picker opens no calendar |
trigger_label(&str), clear_label(&str), panel_label(&str) | What the button, the cross and the panel are called to tooling: “Choose date”, “Clear”, “Choose date” in English |
previous_label(&str), next_label(&str) | What the calendar’s buttons are called |
on_change(Fn(Option<Date>)) | Told of another date, by typing, a choice or the button that empties it; a choice closes the calendar first. Not for the date it holds, nor for the app setting it |
on_input(Fn(&TextInputEvent)) | Told of an edit of the text before it is made, which it may refuse: what is refused is not read |
on_submit(Fn(Option<Date>)) | Told of Enter, once the text is put right, with the date it holds |
on_open_change(Fn(bool)), on_dismiss(Fn()) | Told of the calendar opening and closing, and of Escape or a press outside closing it |
state, style, rules, force, id, key | As an input has them. id is the field’s; the button has it with -trigger, the cross -clear, the panel -panel, the calendar -calendar |
- Its text, the field’s form of a date, how what is typed is read and the names of its button, cross and panel, is its calendar’s
DateText: its own.locale(..), else the app’sapp.set_date_locale(..), else English.trigger_label,clear_labelandpanel_labelare above it. - What is typed is read as it is typed, in the locale’s short form (
Nov 12, 2026), in its numbers (11/12/2026,12.11.2026) or as ISO 8601, a month by its name or the start of it in the locale’s words or in English: a date that can be chosen is the value at once, and the field keeps what is half typed while it has the focus. The year has four digits, soNov 12, 20is no date yet. When the focus leaves the field, or on Enter, the text is written again as the picker writes the value; an emptied field is no date, and anything else takes back the date it had. - The calendar opens in a popover under the field, from the button at its start or from Down in the field, with the focus on the chosen day, today or the first of the month. A choice closes it and the focus goes back to the field, as Escape and a press outside do.
- To what reads the tree the field is a
comboboxthat saysa11y_haspopupdialoganda11y_expanded, as the date picker of the ARIA patterns is; the panel is adialogcalled “Choose date”. The button that opens it and the cross that empties it are pressed by the pointer and take no focus. - In a field the picker is called by the field’s label, judged as the field is, and disabled where it is. A field the app mounts (
Field::mount(ctx)) mounts the picker; a field converted into an element keeps what the picker keeps only where the app gives it aDateMemory. - Parts:
DatePickerPart::Control(rules over the input’s box),TriggerandTriggerIcon(the button at the start and its glyph),ClearandClearIcon,Panel(rules over the popover’s root), and a range picker’sPresets,PresetandSeparator(rules over the line beside them). The field is anInputin the theme’s dress, the panel aPopover, the days aCalendarin the stateBare. States:DatePickerState::Open,Invalid,Warning,Valid,ReadOnly,Disabled,FullWidth, and the input’s size. - In the design the field is the input, 260 by 36, with a calendar’s glyph of 16 in
MutedForeground12 from its start and the date 8 after it in the body’s type. The glyph is in a button of 24 withradius-sm, onHighlightunder the pointer. The calendar opens 4 under the field, in the popover’s panel with no padding of its own, as wide as the calendar. - A theme’s renderer is given
DatePickerView(PickerView<Date>):view.text,view.value,view.open, and the piecescontrol(),trigger(),clear(),field(),calendar(),panel()andrender().
Date Range Picker
Section titled “Date Range Picker”A field that holds a range of dates, typed or chosen from a calendar under it, with ranges offered beside it: the dates of a stay, the period of a report.
use lurq::{ core::{Date, DateRange, Signal}, ui::DateRangePicker,};
let today = Date::today();// period: Signal<Option<DateRange>>DateRangePicker::new(period.clone()) .placeholder("Pick dates") .months(2) .preset("Last 7 days", DateRange::new(today.add_days(-6), today)) .preset("Last 30 days", DateRange::new(today.add_days(-29), today)) .mount(ctx);| Builder | |
|---|---|
new(Signal<Option<DateRange>>), controlled(Option<DateRange>, Fn(Option<DateRange>)) | The range the field holds: bound to a signal, or the app’s |
months(n) | How many months the calendar shows side by side: one as the design draws it, or two |
preset(label, DateRange), presets([(label, DateRange)]) | Ranges offered beside the calendar, after those offered already; a press chooses one and closes the calendar. The one chosen is on the secondary fill |
| everything else | As a date picker’s, over a range: format(Fn(DateRange) -> String), parse(Fn(&str) -> Option<DateRange>), on_change(Fn(Option<DateRange>)), on_submit(Fn(Option<DateRange>)); the button and the panel are called “Choose dates” |
- The range is in one field, as the design draws it:
Nov 9 – Nov 15, 2026, the year once where both ends are in it. What is typed is read as two dates in any form the locale reads, with a dash ortobetween them; the year of the first may be left out where it is the second’s. - In the calendar the first press starts the range, the pointer and the keys show where it would end, and the second press ends it and closes the calendar. Escape or a press outside drops a range half chosen. Neither end may be a day that cannot be chosen.
- The field’s button has the glyph of a calendar’s range; the panel is a
dialogcalled “Choose dates”. - A theme’s renderer is given
DateRangePickerView(PickerView<DateRange>), withpresets()besides the date picker’s pieces.
Event Calendar
Section titled “Event Calendar”A calendar that shows events in its days: the days of a week side by side, the weeks of a month, or one day, each day with what is on it. The meetings of a team, the releases of a project, what is due.
use lurq::{ core::{Date, Signal}, ui::{CalendarEvent, CalendarEventVariant, EventCalendar, EventCalendarPeriod},};
let chosen = Signal::new(None::<Date>);let events = vec![ CalendarEvent::new("standup", monday, "Standup"), CalendarEvent::new("release", tuesday, "Release 0.60").variant(CalendarEventVariant::Success), CalendarEvent::new("freeze", friday, "Deploy freeze").variant(CalendarEventVariant::Destructive),];
// The design's week: five days, no header. Mounted, it keeps the week it shows.EventCalendar::new(chosen.clone(), events.clone()) .weekends(false) .header(false) .on_select(|event: &&str| open(event)) .mount(ctx);
// A month, of which a day shows three events at most and "+2 more".EventCalendar::new(chosen.clone(), events) .period(EventCalendarPeriod::Month) .on_more(|date| show_day(date)) .mount(ctx);| Builder | |
|---|---|
EventCalendar::new(Signal<Option<Date>>, events) | Bound to the chosen day, which a press of a day sets, with its events |
EventCalendar::controlled(value, events, on_change) | It shows value chosen and tells of a press, which it does not set |
event(..), events(..) | Adds to its events |
period(EventCalendarPeriod) | What it shows at once: Week (the default, the design’s), Month, or one Day |
shown(Signal<Date>) | The date whose week, month or day is shown, the app’s: the buttons and the keys that leave the period set it. Without it a mounted calendar keeps it, starting at the chosen day, or today |
weekends(bool) | Whether Saturdays and Sundays are shown: they are unless told. Without them a week is the five days the design draws, and the keys pass a weekend by |
header(bool) | The row at its top: the buttons that show the period before and after, what the period is, and the button that shows today. It has it unless told |
max_shown(usize) | How many events of a day are shown at most: 4 in a week and 3 in a month unless told, all in a day. With more, one fewer are shown and “+N more” in the place of the last |
on_change(Fn(Date)) | A person chose another day: a press or Enter on it, or a press of its “+N more”. Not for the day chosen already, nor when the app sets the value |
on_select(Fn(&T)) | An event was pressed, with what the event is to the app (the first argument of CalendarEvent::new), after the event’s own handlers. A press of an event does not choose its day |
on_more(Fn(Date)) | The “+N more” of a day was pressed, after the day is chosen: an app shows the day alone, or a list of what is on it |
first_day(Weekday), locale(..), today(Date) | The day weeks start on, the words of its dates and the day it marks as today, in place of the app’s locale and the system’s day |
previous_label(&str), next_label(&str), today_label(&str), more_text(Fn(usize) -> String) | The names of its buttons, in place of the locale’s, and what stands for the events not shown, in place of “+N more” |
disabled(bool) | It takes no input |
label(&str) | What its box is called to tooling, which is then a group |
state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. force draws the day Tab would enter at. Each day has the calendar’s id with -day- and its date after it (team-day-2026-11-12), the buttons with -nav-previous, -nav-next and -today, a day’s “+N more” with -more- and the date; its other parts - and the part’s name, by the date where there is one of each day (see ids of parts) |
mount(ctx) | The calendar where it is declared: it keeps the period it shows, and follows the chosen day to its period when the app sets it to a day that is not shown. Converted (.into()) it keeps nothing, and its buttons show no other period unless the app gives it shown |
| Event | |
|---|---|
CalendarEvent::new(value, Date, &str) | What it is to the app (its id, the record it is of), the day it is on, and its title |
CalendarEvent::on(Date, &str) | An event that is no value to the app: its own on_select hears its press |
variant(impl Into<Name>) | Its kind: CalendarEventVariant::Neutral, Info (the default), Success, Warning, Destructive |
on_select(Fn()) | This event was pressed, before the calendar’s on_select |
disabled(bool), id, key | It takes no input; the id and the key of its element |
- Its days are a calendar’s: the weeks of a month are the same grid (
YearMonth::weeks), filled with the days of the months beside it, and the keys are the same, from one function. The days are one stop of Tab, at the chosen day where it is shown, else today, else the first day shown. Left and Right go a day, Up and Down a week, Home and End to the ends of the week, PageUp and PageDown a month and, with Shift, a year, into a period that is then shown. Enter and Space choose the focused day. - Tab goes on from the focused day into its events, each a stop, and then out of the days: an event is pressed with Enter or Space, and its press is its own. The arrows on an event move between the days.
- A press anywhere on a day chooses it. A day of the month beside, in a month, is pressed to choose it and show its month, and is no stop of the keys.
- An event’s title is on one line in a week and a month, cut with an ellipsis where its day is narrower; in the day view, where the room is the day’s, it wraps onto as many lines as it needs.
- In a narrow room. Mounted, the calendar measures the room it is laid out in before the frame is painted, and takes the form that room holds from its first frame (
EventCalendarForm,view.form); the room is its own, so a narrow panel of a wide window is a narrow room too:- A week whose days would be narrower than
EventCalendar::WEEK_DAY_LEAST(110) keeps them at that width, and they scroll sideways inside the calendar, under its header, which stands still (Scrolling). - A week in a room under
EventCalendar::DAY_VIEW_BELOW(330, three such days) shows one day of it (OneDay): the chosen day where it is in the week, else the day the week was shown by. Its title and its buttons are the day view’s, and go a day; the keys are the same, and a press or Enter chooses as ever. With room again it shows the week of that day. - A month whose days would be narrower than
EventCalendar::MONTH_DAY_LEAST(80) shows each day’s number and under it a dot of 6 for each of its events, in the ink of its kind (Dots); a press of a day chooses it and tellson_more, where an app shows what is on it. EventCalendarForm::for_room(period, days, width)is the form of a width. Converted into an element on its own the calendar has no room of its own to read, and keeps the full form.
- A week whose days would be narrower than
- An event is on one day. The events of a day are in the order the app gave them.
- The names of the days and the months, the title of the header and the names of the buttons are the app’s date locale’s (
App::set_date_locale, see dates): a day of a week saysweekday_mediumand its number (“Thu 12”), the header a month’smonth_title, a week’sformat_rangeof its first and last day shown, or a day’sday_label; the buttons sayprevious_week_label,next_week_label,previous_day_label,next_day_label,today_labeland a month’sprevious_month_labelandnext_month_label. - To tooling the days are a
gridcalled by the period shown, ofrows ofgridcells called by their dates, which say whether they are chosen (a11y_selected) and today (a11y_current); a month’s names of the days arecolumnheaders; an event and a “+N more” arebuttons. - Parts:
EventCalendarPart::Root,Header,Title,NavandNavIcon(rules over the buttons’ root and icon),Grid,Weekdays,Weekday,Week,Day(what is pressed and focused),Label(the row at the top of a day),Events,Event(a pill, in its variant’s fill and ink),More,DotsandDot(a month’s dots, in its variant’s ink). States:EventCalendarState::Month,Week,Day(the period),Header,Disabled,Compact(a month of dots),Scrolling(a week that scrolls); a day’sSelected,Current,Outside,Last(the last of its row, and a week the last of the calendar: no line after it); an event’sUnavailable. - In the design (
eh5zV) it is a box onBackgroundin an edge of 1 inBorderwith the large radius, 150 high, its days side by side with a line of 1 after each but the last. A day’s label is a row of 32 with a line under it, padded 10, its text 12 at medium weight inMutedForeground; today’s is onHighlight(the board’s accent) inForegroundat 600. The events are 6 from the day’s sides and 4 apart, each a pill with the small radius padded 4 and 6, its title 11 at medium weight in the color of its kind on that kind’s muted fill. The board draws a week of five days, and nothing else: the header (44 high, a calendar’s buttons, the title at medium weight, an outline “Today”), the month (days at least 115 high under a row of the days’ names, a day of the month beside at half its opacity), the chosen day (its label onPrimary), “+N more” (an event’s box inMutedForeground), the focus (a line of 2 in the ring’s color inside a day or an event) and the event of no kind (Muted,Foreground) are lurq’s. - A renderer that draws another calendar has
view.root(),view.header(),view.nav(by),view.today_button(),view.title_text(),view.grid(),view.weekdays(),view.weeks(),view.week(days, last),view.day(date, last),view.day_text(date),view.day_states(date, last),view.events(date),view.event(event),view.more(date, count),view.entry(),view.bounds(),view.within(date),view.recipe_in(variant, states)andview.render().
Color Picker
Section titled “Color Picker”A color chosen in an area of saturation and brightness, on a rail of hue and one of alpha, from swatches, or typed as hex, RGB or HSL: the color of a label, of a brush, of a theme’s accent.
use lurq::{node::color::Color, ui::{ColorFormat, ColorPicker}};
// The board's: the area, the rail of hue, swatches and the hex.ColorPicker::new(accent.clone()) .swatches(["#3B82F6", "#2DD4BF", "#F59E0B", "#A78BFA", "#F472B6", "#FAFAFA"].map(Color::from_hex)) .on_change_end(|color| save(color));
// With a rail of alpha, and the fields of RGB a button switches to hex and HSL.ColorPicker::new(overlay.clone()) .alpha(true) .format(ColorFormat::Rgb) .formats([ColorFormat::Hex, ColorFormat::Rgb, ColorFormat::Hsl]);
// The color held by the app, told each change.ColorPicker::controlled(series, move |color| set_series(color));| Builder | |
|---|---|
ColorPicker::new(Signal<Color>) | Bound to the app’s color, the engine’s Color: what it shows, and what a person’s change sets |
ColorPicker::controlled(Color, on_change) | The app holds the color: each change is told, and the picker shows what the app answers with. Two built at the one place in the app’s code, in a loop, are told apart by their id or key |
alpha(bool) | A rail of alpha over a checkerboard, and the fields say the alpha. Without it the alpha of the color is kept as it is |
format(ColorFormat) | The fields: Hex (the board’s, one field), Rgb (red, green and blue from 0 to 255) or Hsl (hue in degrees, saturation and lightness in percents) |
formats(..) | The fields a button before them switches between, in order. One or none: no button |
eyedropper(bool), eyedropper_label(&str) | The button at the end of the fields that picks a color from the screen (EyeDropper): shown where the platform can pick, on by default; false hides it anyway. What it is called to what reads the tree: “Pick a color from the screen” |
swatch(color), swatches(..) | Circles of 20 in a row under the rails; a press of one makes the color it, and the one of the color is selected |
on_change(Fn(Color)) | Called with each change a person makes: as a thumb moves, as a key steps, as a swatch is pressed, as a field is committed. Not for what is so already, nor when the app sets the color. Each call adds |
on_change_end(Fn(Color)) | Called once a change is over (a drag let go, a key’s step, a swatch’s press, a field committed), where the color is another than it was as it began. Each call adds |
bare(bool) | Without its panel (fill, edge, corners, shadow): what a popover that holds it draws |
label(&str) | What the picker is called, to what reads the tree: a group |
saturation_label, brightness_label, hue_label, alpha_label, format_label | The words the sliders and the switch say to tooling: “Saturation”, “Brightness”, “Hue”, “Alpha”, “Format” |
disabled(bool), state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. id is the panel’s; the area is {id}-area, the rails {id}-hue and {id}-alpha, the hex {id}-hex, the swatches {id}-swatch-0 and on, the switch {id}-format, a channel {id}-r and the like |
- The area is a slider of two axes: a press or a drag sets saturation across and brightness up, and a drag past its edge keeps the color at the edge. With the focus in it the arrows step by 1%, ten with Shift; PageUp and PageDown step the brightness by 10%; Home and End take the saturation to none and to the whole. The rails are sliders: of hue from 0° to 360° (the true hues, red through yellow, green, cyan, blue and magenta back to red, so that the thumb is at the hue), and of alpha from 0% to 100%; a press or a drag, the arrows by a degree or 1%, ten with Shift, PageUp and PageDown a tenth, Home and End to the ends. A press of the area or a rail gives it the focus, and each is a stop of Tab.
- The picker keeps, while it is in the tree, the hue and saturation its color last had, which a grey and black do not say: moving through the greys does not lose the hue. It keeps the fields a person switched to, and where a drag began.
- The field of the hex reads what is typed on Enter and as the focus leaves, in any form a color is written in (
#2563EB,2563eb,#25e,rgb(37, 99, 235),hsl(221 83% 53%)), and writes the color in capitals, with its alpha where it is not opaque. What is no color takes back the hex. A field of a channel is a bare number input. - To what reads the tree the area is a
slidercalled “Saturation and brightness” whosea11y_valuetextis “Saturation 84%, brightness 92%”; the rails aresliders called “Hue” and “Alpha”, witha11y_valuenow,a11y_valuemin,a11y_valuemaxanda11y_valuetext(“Hue 221°”, “Alpha 50%”). - Parts:
ColorPickerPart::Root(the panel),Area,AreaThumb,Hue,Alpha,Thumb(a rail’s),CheckerandCheckerCell(the checkerboard under the rail of alpha),Swatches,Swatch(laid over a color swatch’s root),Fields,Input(the hex),Format(the switch),FieldLabel(the letter over a channel),EyedropperandEyedropperIcon(the button that picks from the screen, a ghost button of 36 with an icon of 16 inMutedForeground). States:ColorPickerState::Alpha,Bare,Disabled. - The eyedropper starts a pick from the screen; the picker stays as it is while the person picks, and the color picked is a change of theirs:
on_changeandon_change_endare told it once, and nothing where they gave up (Escape) or picked the color it holds. The board draws no eyedropper in the picker: it stands at the end of the fields, where the field’s stands at the end of its box. - In the design the panel is 232 wide in
Popover, with an edge of 1 inBorder, the large radius and the medium shadow, 12 of padding and 12 between what it holds. The area is 208 by 120 with the medium radius: the hue, white over it from its start and black over that from its bottom; its circle is 12, a ring of 2 in white. The rail of hue is 10 high and round at its ends. The swatches are circles of 20, 8 apart; the hex is an input 36 high in the mono type. The board draws no thumb on the rail, no rail of alpha, no fields but the hex and no switch: a rail’s thumb is a circle of 14 with a ring of 2 in white and the small shadow; the rail of alpha is the rail of hue over the checkerboard of a swatch (squares of 5 inBackgroundandMuted); a channel’s letter is 11 inMutedForegroundover its number; the switch is a ghost button 36 high in the mono type at 12. The focus of the area and of a rail is the theme’s ring around it. - The area and the rails are drawn with the engine’s linear gradients: a node has one, so the area is three boxes laid one over another (the hue, white to clear across, clear to black down) and the rail of alpha the checkerboard under the color from clear to whole.
- A renderer that draws another picker has
view.area(),view.hue(),view.alpha_rail(),view.swatches(),view.format_button(),view.hex_field()andview.fields(), each with its behavior, andview.hsv(the color with the hue a grey keeps).
Color Field
Section titled “Color Field”A color typed in a box, or chosen in a color picker that opens under it: the color of a label, of a brand, of a chart’s series.
use lurq::{node::color::Color, ui::{ColorField, Field}};
Field::new("Brand color", ColorField::new(brand.clone()));
// A color or none: emptied, the field holds `None`.ColorField::optional(tint.clone()).placeholder("No tint").alpha(true);
// The color held by the app.ColorField::controlled(series, move |color: Color| set_series(color));| Builder | |
|---|---|
ColorField::new(Signal<Color>) | Bound to the app’s color: what the box and its swatch show, and what is typed or chosen sets |
ColorField::optional(Signal<Option<Color>>) | Bound to a color or none: None shows the placeholder, and emptying the field makes it none. Its on_change is told an Option<Color> |
ColorField::controlled(value, on_change) | The app holds the value (a Color or an Option<Color>): each change is told, and the field shows what the app answers with. Two built at the one place in the app’s code, in a loop, are told apart by their id or key |
on_change(Fn(V)) | Called with the value each time a person changes it: typed and committed, chosen in the picker, emptied. Not for what is so already, nor when the app sets it. Each call adds. The field is ColorField<Color> or ColorField<Option<Color>>, so a handler of another type does not compile |
alpha(bool), format(..), formats(..), swatch(..), swatches(..) | What the picker that opens has: see color picker |
placement(Placement) | Where the picker opens beside the field: under it at its start (the default), flipped where there is no room |
size(ColorFieldSize) | An input’s: Sm 32, Md 36, Lg 40 high, with a swatch of 20, 24 and 32 |
placeholder(&str), invalid, warning, valid, read_only, disabled, full_width, label, name(..) | As an input has them. Read only, nothing typed is taken and the picker does not open. full_width is in place of 180 |
eyedropper(bool) | The eyedropper at the box’s end, which picks a color from the screen (EyeDropper): shown where the platform can pick, on by default; false hides it anyway |
trigger_label(&str), swatch_label(&str), panel_label(&str) | What the eyedropper, the swatch that opens the picker and the popover are called to what reads the tree: “Pick a color from the screen”, “Choose color” and “Color” |
state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. id is the box’s; the swatch is {id}-swatch, the eyedropper {id}-trigger, the popover {id}-panel, the picker {id}-picker |
- What is typed is read on Enter and as the focus leaves, in any form a color is written in, as the picker’s hex is: a color is the value and is written again as its hex in capitals, an emptied optional field is none, and anything else takes back the hex. The box keeps what is half typed while it has the focus.
- The picker opens in a popover under the field from the swatch at its start or Down in the box, with the focus in its area; a change in it sets the field’s value at once. Escape and a press outside close it, and the focus goes back to the box; Tab from its last field goes on past the field. The field keeps, while it is in the tree, whether its picker is open.
- The eyedropper picks a color from the screen, where the platform can: the color picked is the field’s value, as a person’s change (
on_change), and the picker, open or not, stays as it is while the person picks. Where the platform cannot pick, there is no eyedropper; the picker in the field’s popover has none of its own. - To what reads the tree the box is a
comboboxcalled by its label, which says it opens adialogand whether it is open; the swatch and the eyedropper take no focus. - Parts:
ColorFieldPart::Root(its width),Control(the box typed in),Placeholder,Swatch(laid over a color swatch’s root),Trigger(the eyedropper’s button),TriggerIcon,Panel(over the popover’s). States:ColorFieldState::Invalid,Warning,Valid,ReadOnly,Disabled,FullWidth,Open. - In the design the field is 180 by 36, an input’s box (the
Backgroundfill in an edge of 1 inInput, 6 round), the swatch of its color (24) 6 from its start, its hex 8 after it in the mono type at 13 inForeground, and an eyedropper of 16 inMutedForeground6 from its end. The board draws it at rest only: under the pointer, focused, judged, read only and disabled it is an input; the eyedropper is in a button of 24 with the small radius, onHighlightunder the pointer; while the picker is open the edge is inRing. The picker opens 4 under it in a popover whose panel is the picker’s, 232 wide. - A renderer that draws another field has
view.control(),view.swatch(),view.trigger(),view.field()andview.panel().
Color Swatch
Section titled “Color Swatch”One color, shown as a small square or circle: a color an app has, a choice among colors, what a color field holds.
use lurq::{node::color::Color, ui::{ColorSwatch, ColorSwatchShape, ColorSwatchSize}};
ColorSwatch::new(Color::from_hex("#2563EB")).label("Brand blue");// Not opaque: over a checkerboard.ColorSwatch::new(Color::from_hex("#2563EB80")).shape(ColorSwatchShape::Round);// Pressed: a button.ColorSwatch::new(amber).size(ColorSwatchSize::Lg).on_click(move |_| choose(amber));| Builder | |
|---|---|
ColorSwatch::new(impl Into<Color>) | A swatch of the color |
size(ColorSwatchSize) | Sm 20, Md 24 (the board’s), Lg 32 square |
shape(ColorSwatchShape) | Square (the small radius, the board’s) or Round |
selected(bool) | A ring of 2 in Foreground around it: the one chosen |
on_click(handler) | A click, and Enter and Space while it has the focus: the swatch is then a button, a stop of Tab. Each call adds |
label(&str) | What it is called, to what reads the tree: its color’s hex in capitals where it has none |
disabled(bool), state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them |
- A color that is not opaque stands over a checkerboard of squares of 4,
BackgroundandMuted. - To what reads the tree a swatch is an
imgcalled by its label or its hex; one withon_clickis abutton, witha11y_pressedwhere it is selected. - Parts:
ColorSwatchPart::Root,Checker(the light squares),CheckerCell(the dark squares and their side). States:ColorSwatchState::Selected,Round,Pressable,Disabled. Sizes:ColorSwatchSize. - In the design a swatch is 24 square with the small radius and an edge of 1 in
Borderinside it. The board draws none focused or disabled: the focus is the theme’s ring, and a disabled one is dimmed as every control is.
Drop Zone
Section titled “Drop Zone”Where files are dropped from the system, or chosen in its file dialog: images for a gallery, a document to import. It says what a drag over it will do, takes what it accepts, and tells the app what it refused.
use lurq::ui::DropZone;
DropZone::new() .accept(["image/*", "pdf"]) .max_size(5 * 1024 * 1024) .description("PNG, JPG or PDF, up to 5 MB") .on_files(|files| upload(files)) .on_reject(|refused| say_why(refused)) .mount(ctx);| Builder | |
|---|---|
DropZone::new() | A zone that takes any number of files of any kind and size |
accept(impl IntoIterator<Item = &str>) | The files it takes: extensions ("png", ".png") and kinds ("image/*", "video/*", "audio/*", "text/*", "archive/*"), in any case. A second call adds. Nothing accepted takes every file |
multiple(bool) | More than one file at once: on unless told. Off, the first is taken and the rest refused as too many |
max_size(u64), max_files(usize) | The greatest size of a file in bytes (a file whose size is not known is taken), and the most files of one drop or choice |
icon(impl Into<IconChoice>) | The icon over its words in place of the upload icon, or None |
title(&str), description(&str), no_description() | What it says, in place of “Drop files here” and “or click to browse” |
drop_text(&str), reject_text(&str) | What it says while files it takes, or files it takes none of, are dragged over it, in place of “Drop to add” and “These files can’t be added” |
label(&str) | What it is called to tooling, and its dialog’s title; its title where it has none |
invalid(bool), disabled(bool) | Its edge in the destructive color; or it takes no drop and no press, dimmed |
on_files(Fn(&[DroppedFile])) | Called with the files it took from a drop or from its dialog, in their order |
on_reject(Fn(&[RejectedFile])) | Called with the files it refused and why: RejectReason::Kind, TooLarge, TooMany, Folder |
mount(ctx) | The zone mounted where it is declared: it shows a drag over it, and a press, Enter or Space opens the system’s dialog |
state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. state(DropZoneState::DragOver, true) draws a drag with none |
- It is a stop of Tab, a
buttonto tooling called by its label. A press, Enter or Space opens the system’s dialog for files to open (lurq::files::FileDialog, with the featurefile_dialog), filtered by the extensions it accepts; a second press while the dialog is open opens no second one. What is chosen is sorted as a drop is. - A drag over it is taken where it takes at least one of its files; one it takes none of is refused (
FileDragEvent::refuse) and drawn so. The drop giveson_fileswhat it takes andon_rejectthe rest, each only where there is something to tell. A folder is refused. - Showing a drag and opening the dialog are what the mounted zone does: converted into an element on its own it is its still form, which takes a drop, shows no drag and opens nothing.
- Parts:
DropZonePart::Root(the zone),Icon,Text(the column of the title and the description),Title,Description. States:DropZoneState::DragOver,Rejected,Invalid,Disabled,Icon,Description. - In the design the zone is 320 by 140 on
Muted, with the large radius and an edge of 1.5 inInputinside it; in its middle the upload icon of 20 inMutedForeground, 8 over “Drop files here” in 14 medium inForegroundand “or click to browse” in a caption’s 12 inMutedForeground. The board draws it at rest only: a drag it takes is drawn as the board’s Drop Target, onInfoMutedwith an edge of 2 inInfoand its icon and title inInfo; a drag it refuses the same inDestructiveMutedandDestructive. Under the pointer its edge isRing, focused from the keyboard it has the focus ring, invalid its edge isDestructive. A longer title wraps and the zone grows; it is padded 24 across and 16 down for that, which the board’s zone, of three short lines, does not show. - In a field it is called by the field’s label, invalid where the field is, and disabled where it is.
- A renderer that draws another zone starts from
view.zone(), the element files are dropped on and that is pressed, and putsview.icon()andview.text()in it, or what it likes.
File Upload
Section titled “File Upload”The files a person gives, by the system’s file dialog or a drop, in a list with how far each is sent. The app sends them and says how far: lurq sends nothing.
use lurq::{files::DroppedFile, ui::{FileUpload, UploadFile}};
// files: Signal<Vec<UploadFile>>FileUpload::new(files.clone()) .accept(["image/*", "json"]) .on_files(|given| send(given)) .on_retry(|file| send_again(file)) .mount(ctx);
// As the app sends them, it moves each file on.files.update(|files| files[0] = files[0].clone().uploading(0.62));| Builder | |
|---|---|
FileUpload::new(Signal<Vec<UploadFile>>) | Bound to the app’s list: what is given is added as waiting and a removed file is taken out, then the handlers are told |
FileUpload::controlled(files, on_change) | The list the app holds: a person’s change is told to on_change as the whole new list, and the upload shows what the app answers with |
FileUpload::at(files) | A list shown and not operated: nothing is given, removed or sent again |
accept, multiple, max_size, max_files | What it takes, as a drop zone’s; max_files counts the files the list holds |
zone(bool) | A drop zone in place of the button; title and description are the zone’s words |
choose_label(&str) | What the button says, in place of “Choose files” |
remove_label(&str), retry_label(&str) | What a file’s controls are called before its name, in place of “Remove” and “Retry” |
size_text(Fn(u64) -> String) | How a file’s size is said, in place of “4 KB” and “1.2 MB” (lurq::files::format_size) |
label(&str), invalid(bool), disabled(bool) | What it is called to tooling and its dialog’s title; its button’s or zone’s edge destructive; nothing given or removed, its list dimmed |
on_change(Fn(&[UploadFile])) | Called with the whole new list a person made; bound, after the signal is set |
on_files(Fn(&[DroppedFile])), on_reject(Fn(&[RejectedFile])) | Called with the files given, which the app sends, and with those refused and why |
on_remove(Fn(&UploadFile)), on_retry(Fn(&UploadFile)) | Called with a file a person removed (one being sent is to be stopped), and with a failed file to send again (the app sets it uploading) |
mount(ctx) | Mounted where it is declared: its button or zone opens the system’s dialog, the zone shows a drag, and the focus of a removed file’s control goes on |
state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. With an id, the button or zone is <id>-trigger, a file <id>-<file's id>, its controls <id>-<file's id>-remove and -retry |
UploadFile | |
|---|---|
UploadFile::new(DroppedFile) | A file waiting to be sent. Its id, what the app finds it by, is its path, else its name |
uploading(f32), done(), failed(&str), waiting() | Where it is: being sent, a fraction from 0 to 1 of the way; sent; not sent, and why; waiting again |
id(..), key(..), disabled(bool) | Its id in place of its path; the key of its element; whether a person may not remove it or send it again |
- Files dropped anywhere on it are given as a drop zone’s are, and a drag it takes nothing of is refused. Tab reaches the button, then each file’s controls in order; Enter or Space presses them. Mounted, a removed file’s control gives the focus to the next file’s, else the one before, else the button.
- A file says its size while it waits and once it is sent, and how far it is while it is sent, with a bar under its line. A failed file says why under its line and has a retry control before its remove control. A file that was sent has the check and no control: the app takes it out where it likes.
- A name longer than its line ends in an ellipsis; its size keeps its room.
- Parts:
FileUploadPart::Root,Trigger(the button, whose rules are laid over a button’s root),List,Item,Icon(the icon of the file’s kind: an image, a text, an archive, a file),Text,Label(the name),Meta(the size or how far),Progress,Error,Status(the check),Remove,Retry. States:FileUploadState::Zone,Invalid,Disabled, and on a file’s partsWaiting,Uploading,Done,Failed,Unavailable(a disabled file). - In the design the upload is 300 wide: the outline button of 36 with the upload icon, and 8 under it the files 8 apart. A file is a row with an edge of 1 in
Borderinside it, the medium radius, padded 12 across and 10 down, its parts 10 apart: the icon of its kind, 16 inMutedForeground; its name in 13 medium inForeground, and 8 after it its size or how far in 11 mono inMutedForeground; while it is sent a progress of 4, 6 under the line; at the end the check inSuccessor the remove control of 16 inMutedForeground. The board draws no failed file: its edge and its icon areDestructive, its error in a caption’s 12 inDestructive. With a zone it is 320 wide, the zone’s. - In a field it is called by the field’s label, invalid where the field is, and disabled where it is.
- A renderer that draws another upload has
view.trigger(),view.item(index),view.list(), andview.files;view.item_part(index, part)is a part in its file’s state.
Date Field
Section titled “Date Field”A date typed in by its segments, the day, the month and the year, each stepped by the arrows: a date of birth, a date in a form where a calendar would be in the way.
use lurq::{ core::{Date, Signal}, ui::{DateField, DateMemory, Field},};
// born: Signal<Date>; mounted, so that it keeps what is half typed.DateField::new(born.clone()).label("Date of birth").mount(ctx);
// A date that may be none, in a field; the field mounted mounts the date field.Field::new("Due date", DateField::optional(due.clone()).min(Date::today())).mount(ctx);| Builder | |
|---|---|
new(Signal<Date>), optional(Signal<Option<Date>>) | The date the field holds, which a date typed whole sets; optional holds none while a segment is empty |
controlled(Date, Fn(Date)), controlled_optional(Option<Date>, Fn(Option<Date>)) | The app’s date, and what it is told of a date typed, which the field does not set |
memory(&DateMemory), mount(ctx) | What it keeps of what is half typed and which segment has the focus: the app’s, or its own where it is mounted |
min(Date), max(Date) | The least and the greatest date that is the field’s: one typed out of them is no value |
today(Date) | The day an empty year starts at under the arrows |
locale(impl DateText) | The order of the segments, what stands between them, their names and what an empty one shows |
icon(impl Into<IconChoice>) | The glyph at the end: the calendar’s, or None |
size(DateFieldSize), invalid, warning, valid, read_only, disabled, full_width, label, name | As an input’s; DateFieldSize is TextBoxSize. The form holds the date in ISO 8601 |
on_change(Fn(V)) | Told of another date: once every segment is filled, or, for optional, when one is emptied. Not for the app setting it |
state, style, rules, force, id, key | As an input has them. Each segment has the id with its name after it: due-day, due-month, due-year |
- Each segment is a spin button and a stop of Tab, as a browser’s own date input and the date fields of macOS are: Tab and Shift+Tab go from one to the next, and so do Left and Right. Digits fill the focused segment and go on to the next once it is full, or once no other digit could follow (
4is April). Up and Down step it, round from the last to the first, and an empty year starts at this year; Home and End go to its ends; Backspace takes the last digit typed, or empties it. - The value is a date only when every segment is filled with a day that exists and is in the range. Until then a field of
newkeeps the date it had, one ofoptionalholds none, and what is typed stays. A date the app sets shows in place of what was typed. - To what reads the tree the field is a
groupcalled by its label, ofspinbuttons called by the segment’s name (Month) that saya11y_valuenow,a11y_valuemin,a11y_valuemaxanda11y_valuetext(November). - Its text is its
.locale(..), else the app’sapp.set_date_locale(..), else English, which writes the month first (11/12/2026);en-GBwrites the day first, as the board draws it. - Parts:
DateFieldPart::Root(the box),Segments(the row of segments, its gap),Segment,Separator,Icon. States:DateFieldState::Invalid,Warning,Valid,ReadOnly,Disabled,FullWidth; of a segmentFocusedandPlaceholder. - In the design the box is 180 by 36 on
Background, an edge of 1 inInput,radius-mdand 10 of padding; its segments, 2 apart, are in the mono type at 13 inForeground, 19 high with 3 of padding across and a radius of 3, the separators inMutedForeground. The segment with the focus is the box’s selected text, onSelectioninForegroundas a text input’s selection is; the board fills it withinfounder white, for which the palette has no pair of roles. A calendar’s glyph of 16 inMutedForegroundis at the end. An empty segment, which the board does not draw, showsdd,mm,yyyyinMutedForeground. - A theme’s renderer is given
DateFieldView(SegmentFieldView):view.segments(each aSegmentShown), and the piecessegment(index),separator(index),segments_row(),icon()andrender().
Time Field
Section titled “Time Field”A time typed in by its segments, as a date field is a date: the time of a meeting, an alarm, the opening hours of a shop.
use lurq::{ core::{Signal, Time}, ui::TimeField,};
// starts: Signal<Time>; the minutes step by a quarter of an hour.TimeField::new(starts.clone()).label("Starts at").step(15).mount(ctx);
// With seconds, a time that may be none.TimeField::optional(lap.clone()).seconds(true).mount(ctx);| Builder | |
|---|---|
new(Signal<Time>), optional(..), controlled(..), controlled_optional(..) | As a date field’s, of a Time |
step(minutes) | What Up and Down step the minutes by: 1, or 15 for a quarter of an hour. Any minute may be typed |
seconds(bool) | A segment for the seconds. Without it the value’s seconds are kept as they are |
hour_cycle(HourCycle) | From 0 to 23, or from 1 to 12 with a last segment for AM and PM, in place of the locale’s |
| everything else | As a date field’s: min(Time), max(Time), locale, memory, icon (the timer’s), the input’s sizes and states |
- Its segments are a date field’s. On a clock of twelve hours the last is the half of the day, which
A,Pand the arrows set. Up and Down go round the clock: 23 is before 0, and a step of 15 goes from 45 to 0. - In the design the box is 120 by 36, the hours and the minutes with a colon between them, a timer’s glyph at the end; it is wider for its seconds and its half of the day. Its parts and states are the date field’s (
DateFieldPart,DateFieldState).
Time Picker
Section titled “Time Picker”A field that holds a time, typed in it or chosen from columns of hours and minutes that open under it: the time of a meeting, a reminder, a delivery slot.
use lurq::{ core::{Signal, Time}, ui::TimePicker,};
// at: Signal<Time>; the minutes offered by the quarter of an hour.TimePicker::new(at.clone()).step(15).mount(ctx);
// Half hours of an afternoon, the panel drawn in place.TimePicker::new(slot.clone()) .step(30) .min(Time::new(13, 0, 0).unwrap()) .max(Time::new(16, 0, 0).unwrap()) .inline(true) .mount(ctx);| Builder | |
|---|---|
new(Signal<Time>), optional(..), controlled(..), controlled_optional(..) | The time the field holds: typed, or chosen from the panel |
step(minutes) | The minutes the panel offers apart: 15 as the board draws them |
hour_cycle(HourCycle) | From 0 to 23, or from 1 to 12 with a column of AM and PM |
min(Time), max(Time) | What can be typed or chosen: the hours and minutes out of it are not offered |
memory(&DateMemory), mount(ctx), open(Signal<bool>) | Whether the panel is open and the field it opens under |
placement, offset, collision, inline | As a date picker’s panel |
trigger_label(&str), panel_label(&str) | What the button and the panel are called to tooling: the locale’s Choose time |
placeholder, locale, size(TimePickerSize), invalid, warning, valid, read_only, disabled, full_width, label, name | As a date picker’s |
on_change(Fn(V)), on_input(Fn(&TextInputEvent)), on_submit(Fn(V)), on_open_change(Fn(bool)), on_dismiss(Fn()) | As a date picker’s; a minute closes the panel before on_change is called |
- What is typed is read as it is typed (
9:30,14:05,2:05 pm) and is the value as soon as it is a time in the range; the focus leaving and Enter write it as the locale writes times. - The panel opens from the button at the start of the field and from Down in it, the focus on the hour held, each column scrolled to its item. A press of an hour sets the hour and leaves the panel open; a press of a minute sets the minute and closes it, the focus back in the field.
- To what reads the tree the field is a
comboboxthat opens adialogoflistboxes called by the segment’s names, ofoptions. - Parts:
TimePickerPart::Control(rules over the input’s box),Trigger,TriggerIcon,Panel(rules over the popover’s panel),Column,Item. States:TimePickerState::Open, the field’s, and of an itemSelected. - In the design the field is an input 160 by 36 with a timer’s glyph of 16 at its start and the time 8 after it in the mono type at 14; the panel opens 4 under it, 160 wide, with 4 of padding and 4 between its two columns, items 74 by 30 and 2 apart with
radius-sm, their numbers in the mono type at 13, the held one onHighlightat 500. Four items of a column are seen; it scrolls.
Month Picker
Section titled “Month Picker”The twelve months of a year, of which a person chooses one, and the years before and after under the buttons of its heading: the month of a report, the expiry of a card.
use lurq::{ core::{Signal, YearMonth}, ui::{MonthPicker, YearPicker},};
// month: Signal<YearMonth>; mounted, so that it keeps the year it shows.MonthPicker::new(month.clone()).max(YearMonth::current()).mount(ctx);
// year: Signal<i32>YearPicker::new(year.clone()).min(1900).mount(ctx);| Builder | |
|---|---|
new(Signal<YearMonth>), optional(..), controlled(..), controlled_optional(..) | The month the picker holds, which a press sets |
min(YearMonth), max(YearMonth) | What can be chosen: the months out of it are muted, and the years beyond are not shown |
today(YearMonth) | The month marked as this month |
locale(impl DateText) | The months’ short names (Nov, Лис) and the buttons’ names |
previous_label(&str), next_label(&str) | What the buttons are called: the locale’s Previous year, Next year |
memory(&DateMemory), mount(ctx) | The year shown, between renders |
label, invalid, disabled | Its name to tooling, which makes the panel a group; a field’s judgment; no input |
on_change(Fn(V)) | Told of another month chosen; not for the one chosen, nor for the app setting it |
state, style, rules, force, id, key | Each month has the id with -cell- and the month after it: due-cell-2026-11 (a year picker’s year due-cell-2026); the buttons -nav-previous and -nav-next |
ui::YearPickeris one of years:YearPicker::new(Signal<i32>)and the same builder overi32, twelve years from the start of a decade (2020 – 2031), the buttons going ten years, calledPrevious yearsandNext years.- To the keyboard the cells are one stop of Tab, at the chosen one, this one or the first that can be chosen: Left and Right go one, Up and Down four (a row), Home and End to the ends of the row, PageUp and PageDown a page (a year of months, ten years), into the page before or after, which is then shown. Enter and Space choose. To what reads the tree the cells are a
gridcalled by its heading, ofgridcells that saya11y_selected,a11y_currentanda11y_disabled. - Parts:
MonthPickerPart::Root(the panel),Header,Title,NavandNavIcon(rules over the bare buttons),Grid,Row,Cell. States:MonthPickerState::Disabled; of a cellSelected,Current,Unavailable. - In the design the panel is 252 wide on
Popoverwith an edge of 1 inBorder,radius-lg, the popover’s shadow and 12 of padding; the heading, 28 high, has the year in the body’s type at 500 between two bare chevrons of 16 inForeground, 8 over the grid. The months are in three rows of four, 8 apart, cells 34 high and 4 apart withradius-md, their names at 13; the chosen one is onPrimary, its name inPrimaryForegroundat 500. This month, which the board does not draw, is onHighlightas a calendar’s today is; one out of the range is muted at half opacity. - A theme’s renderer is given
MonthPickerView(PeriodsView, aYearPickerViewtoo):view.title,view.cells(each aCellShown), and the piecesnav(by),header(),cell(index),grid()andrender().
Rows one under the other: settings, people, files, notifications. A row has a title, a description under it, what stands before it and what stands at its end.
use lurq::ui::{Avatar, List, ListItem, Switch, icons};
List::new() .item( ListItem::new("Ivan Zaida") .description("Pushed 3 commits to feat/node-blur") .leading(Avatar::new("Ivan Zaida")) .meta("2m"), ) .item(ListItem::new("Dependabot").description("Bumped wgpu to 26.0").selected(true));
// Settings: a value and a chevron where a row leads somewhere, a switch where it holds one.List::new() .separators(true) .inset(40.0) .item(ListItem::new("Wi-Fi").icon(icons::WIFI).value("Home").chevron(true).on_click(|_| open_wifi())) .item(ListItem::new("Dark mode").icon(icons::MOON).trailing(Switch::new("Dark mode").label_hidden(true)));
// A contained list: the rows in a box, under a header.List::new().contained(true).title("Recent").item(ListItem::new("theme.md").chevron(true).href("/docs/theme"));| Builder | |
|---|---|
ListItem::new(title) | A row that says title, with nothing before or after it |
description(&str) | A second line under the title, in the muted color |
title_pending(bool), description_pending(bool) | The title or the description is still read: a skeleton’s bone stands in place of its words, as wide and as high as the recipe’s part TitleSkeleton (140 by 12) or DescriptionSkeleton (220 by 10) says, giving way in a narrower row, on a line of the text’s height, so that the words that come move nothing (part Title or Description holds it, x-title; the bone is x-title_skeleton, x-description_skeleton). A description still read draws the row as one of two lines whether it has one yet or not. The row says a11y_busy to tooling, is still called by its title, and tells no description while it is read. Style a bone’s width for one row with style(ListItemPart::TitleSkeleton, |s| s.width(96.0)) |
tag(element), info(&str) | The app’s elements after the title on its line, 6 after it and 6 apart (a tag that says Default, a badge; part ListItemPart::Tags), and the mark of an info label after them, its words in a tooltip above it wherever the row is rendered (part Info). The title gives way before them, and a press of the mark is not the row’s |
subtitle(element) | An element of the app’s on a line of its own under the title’s line and over the description, in the text’s column (part Subtitle, x-subtitle, x-subtitle-2): the value a setting names, such as a program’s path, with the description that says more under it. Its presses are its own |
detail(element) | An element of the app’s under the description, in the text’s column, 2 under it (part Detail): a link that says more, a path on a line of its own. Its presses are its own |
below(element) | What the row says under itself: a problem, a question, a code to copy. It stands across the row under the line of its title and its end, 12 in from the sides (14 in a setting) and 8 above the bottom (12 in a setting), one under another 8 apart (part Below); a list’s line is under it, and a press of it is not the row’s. The row’s id is on the line that is pressed; what holds both is the part Item (x-item), with the row’s key |
leading(element), icon(name) | What stands before the text: an avatar, a picture; or an icon of the theme’s set |
checkbox(bool), radio(bool) | A checkbox or a radio before the text, checked or not: the row is that control, which its press changes through on_click |
value(&str), meta(&str) | A value at the end in the muted color (“Home”), or a note in the mono type (“2m”) |
trailing(element), shortcut(keys), chevron(bool) | What the app puts at the end (a switch, a badge), the keys that do what the row does, and a chevron for a row that leads somewhere |
on_click(handler), href(path) | What a press does, given the press (Fn(MouseEvent)), or where it goes in the app’s router: the row is pressed. A second handler is called after the first |
on_open_aside(handler), tab_stop(bool) | Called, given the press, for the middle button or a press with Ctrl held (Cmd on macOS) in place of on_click and the path; and false, a pressed row Tab passes by and a press does not focus. See pointer-only pressables |
selected(bool), disabled(bool), density(Density) | The selected row is highlighted; a disabled one is dimmed and takes nothing; how high it is, whatever the theme is at |
List::new(), item(row), items(rows) | The rows, one under the other |
separators(bool), inset(f32) | A line between each two rows, and how far from the start it starts |
contained(bool), title(&str), action(element) | The rows in a box, touching, under a header with a title (in capitals) and an action: the one action, a second takes its place |
label(&str), density(Density), force(..) | What the list is called to what reads the tree; the density of every row; every row drawn as under the pointer or focused |
state(name, on), style(part, ..), rules(&recipe), id, key | As a button has them, on the row and on the list |
- A row given
on_clickorhrefis pressed: by the pointer, and by Enter and Space while it is focused, and Tab stops at it. A row that is not pressed is not a stop of Tab and answers no pointer: a control in it (a switch at its end) is pressed on its own. In a row that is pressed, what the app put at its end withtrailingkeeps its own presses, which are not the row’s, and is a stop of Tab after the row. A title longer than its room is cut with an ellipsis, and a description goes on to the next line. In a list Up and Down, Home and End move between the rows that are pressed and the controls in rows, and a letter to the next whose title starts with it. - A row with
hrefgoes to its path in the router around it (router::current_navigator), after itson_click; outside a router it goes nowhere. - What is selected is the app’s:
selected(true)on the row. A list of which one or many are chosen by a person is a listbox. - To what reads the tree a list is a
listcalled by its label or its title. A row is alistitem; a pressed one abutton, alinkwith a path, acheckboxorradiowith one before its text (witha11y_checked), and a selected one saysa11y_selected. - Parts of a row:
ListItemPart::Root(what is pressed, selected and focused),Leading,Icon,Content,Title,Subtitle,Description,Tags,Info,Detail,Below,Trailing,Value,Meta,Chevron,TitleSkeletonandDescriptionSkeleton(the bones while the words are read),Item(the row and what it says below, where it says something). Given an idx, the title isx-titleand the descriptionx-description. The idxis on the row, what is pressed, as on every pressed component; a row that says something below is held with it inx-item. An app whose rows had a frame<id>-rowand a pressed part<id>-openreadsx-item(orx, where the row says nothing below and is the whole item) andx. States:ListItemState::Selected,Disabled,Pressable,Description(it has one),Icon(what is before its text is an icon),Contained,Setting(it is a row of a settings card, which draws it as the design’s Settings Row). Parts of a list:ListPart::Root,Header,Title,Action,Items,Separator(what holds a line; its padding at the start is the inset). States:ListState::Contained,Separator. - In the design a row is 36 high (28, 44 and 56 at the compact, comfortable and touch densities), 12 in, with the medium radius and 12 between what it holds; with a description it is 16 higher, 52 at the default, its title at 500. The title is the body’s type at 14, the description 12 in
MutedForeground2 under it, a value 13 and a chevron of 14 inMutedForeground, a note the mono type at 11, an icon 16 inMutedForeground. The selected row is onHighlight. A pressed row under the pointer and held down has theStateHoverandStatePressedveils, the focus from the keyboard is a ring of 2 inRinginside it, and a disabled row is half opaque. Under a finger a row is the board’s mobile row: 56 high, 16 in, its title at 16, its value at 15, its chevron 18, its icon of 18 on a tile of 32 onMutedwith the large radius. - Rows are 2 apart; with lines between them they touch, a line of 1 in
Borderfrom the inset to the end along the bottom of the row over it, inside it: the lines add no height, and a contained list of three rows is 32 + 3 × 36 = 140, as the board’s is. A disabled row saysa11y_disabledto tooling. A contained list is a box onBackgroundwith an edge of 1 inBorderand the large radius; its header is 32 high onMuted, 12 in, with a line under it, its title the mono type at 11 inMutedForeground, 1 apart; its rows are square, their titles 13 and 8 from what is at their end. - A theme’s renderer is given
ListItemView(view.root(children),view.leading(),view.content(),view.trailing(),view.below(),view.render(),view.bone(text, bone)for a bone in a text’s place;view.tags,view.info,view.subtitles,view.details,view.title_pending,view.description_pending) andListView(view.root(),view.header(),view.rows(),view.separator()).
Listbox
Section titled “Listbox”A list in the page of which one option is chosen, or any number: a renderer, a time zone, the columns a table shows.
use lurq::{components::SelectOption, ui::Listbox};
// renderer: Signal<&str>Listbox::new(renderer, [ SelectOption::new("wgpu", "wgpu").group("Renderers"), SelectOption::new("dx12", "DirectX 12"), SelectOption::new("metal", "Metal"), SelectOption::new("gl", "OpenGL (legacy)").disabled(true),]).label("Renderer");
// None chosen until an option is: a Signal<Option<&str>>, and on_change is told the Option.Listbox::optional(theme, [("light", "Light"), ("dark", "Dark")]).on_change(|theme: &Option<&str>| save(*theme));
// Any number: a Signal<Vec<&str>>, and on_change is told the whole set.Listbox::multiple(columns, [("name", "Name"), ("size", "Size"), ("kind", "Kind")]).label("Columns");
// What is chosen held by the app: it is told, and answers.Listbox::controlled(renderer, options, move |chosen: &&str| ask_to_switch(*chosen));
// A long list scrolls in a box with a most height.Listbox::new(zone, zones).style(ListboxPart::Root, |s| s.max_height(240.0));
// Thousands of options: in a virtual list, in a box with a height.Listbox::new(item, items).style(ListboxPart::Root, |s| s.height(320.0)).mount(ctx)| Builder | |
|---|---|
new(value, options) | Bound to a Signal<T>: the option of its value is chosen, and choosing another sets it. Options as a select takes them: (value, label), a Choice, or a SelectOption with group, detail, hint, leading, trailing, disabled |
optional(value, options) | Bound to a Signal<Option<T>>: as new, with none chosen while it is None |
multiple(values, options) | Bound to a Signal<Vec<T>>: the options of its values are chosen, and choosing one adds it or takes it out |
controlled(value, options, on_change), controlled_optional(..), controlled_multiple(..) | The same three, held by the app: a T, an Option<T> or the values, chosen as it says; on_change is told what a press or a key would choose, and the listbox shows what the app answers with |
follow_focus(bool) | Of one, whether the arrows choose as they move. They do unless told otherwise; without it Space, Enter and a press choose |
checkboxes(bool) | Of many, a checkbox before each option’s label, ticked while it is chosen, in place of the check at its end and the highlight: a press checks one or unchecks it and keeps the rest, a press with Shift and Shift with the keys check a range and keep what else is checked. A transfer’s lists are these |
on_change(handler) | Told the new choice after each press or key that changes it, after the signal is set, and not for what is already chosen nor when the app sets the signal: &T of a listbox made with new or controlled, &Option<T> of an optional one, &[T], the whole set, of a multiple one. A handler of another type does not compile. A second handler is called after the first |
label(&str) | What it is called, to what reads the tree. A field gives it its label |
invalid(bool), disabled(bool), full_width(bool), density(Density) | Its edge in Destructive; no option chosen; as wide as what holds it, in place of 220; how high an option is |
state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. id is the id of the box; each option’s is that id, - and its place from 0 |
mount(ctx) | In place of building it: the options in a virtual list, which builds only those near the view, for thousands. Give Root a height |
- It is one stop of Tab, at the chosen option or the first. Up and Down move through the options, Home and End to the first and the last, PageUp and PageDown by what the box shows, without going round, and a letter to the next option that starts with it; a disabled option is passed by.
- Of one, the choice follows the focus, as in a radio group: a key that moves the focus chooses what it moves to, a letter too. With
follow_focus(false)the focus and the choice are apart: the focus moves alone and Space, Enter or a press choose. - Of many, a press chooses one alone, with Ctrl (Cmd) it adds or takes out one, with Shift it chooses from the last chosen to it. Space adds or takes out the focused option; Shift with the arrows, Home, End and the page keys chooses from where the choice started to where the focus goes; Ctrl+A chooses every option that can be. The last of the
Vecis where a range starts. - The keys are the engine’s: the options are a focus group that is
one_stop, withtypeahead,pagesand withoutwrap; one of oneactivates, one of manyshift_extends. The range and the toggle areui::selection’s, which the tree view shares. - Mounted with
mount(ctx), the options are in the engine’s virtual list and the group steps over every option, built or not (FocusRows): the keys, the page keys and typeahead go to any option, the list builds it and the focus goes to it, and the choice follows as it does where every option is built; Shift with the keys and Ctrl+A choose over every option. The list opens at the chosen option. Each option is drawn withListboxOption::render, its group’s label over it; a theme’s renderer of the whole listbox is not used there, its rules are. - To what reads the tree it is a
listbox(a11y_multiselectableof many) called by its label, withoptions that saya11y_selected,a11y_posinsetanda11y_setsize; a group’s label is agroup. - Parts:
ListboxPart::Root(the box; its most height makes the options scroll),Content(the options with the keys),Group,Option,Leading,Label,Detail,Hint,Trailing,Check. States:ListboxState::Chosen,OptionDisabled,Detail(of an option),Checkboxes,Disabled,Invalid,Multiple,FullWidth. - In the design the box is 220 on
Backgroundwith an edge of 1 inBorderand the large radius, its options 1 apart, 4 in. An option is 32 high (24, 40 and 44 at the compact, comfortable and touch densities), and 16 higher with a detail under its label (48; 40, 56 and 60), 8 in, with the small radius, its label in the body’s type at 13. The chosen one is onHighlight, its label at 500, with a check of 14 at its end; the one under the pointer is onMuted; one held down has theStatePressedveil; the focus from the keyboard is a ring of 2 inRinginside it; a disabled one says its label inMutedForeground, faded, is drawn as nothing points at it or presses it whatever the listbox is forced to, and saysa11y_disabledto tooling. A group’s label is 11 at 600 inMutedForeground, 6 over it, 4 under it, 8 in. - A theme’s renderer is given
ListboxView:view.options(each aListboxOptionwith its label, group, detail, whether it is chosen and disabled, andoption.button(),option.group_label(),option.text(),option.check(),option.checkbox(),option.render()),view.content()(the column with the keys) andview.root(content). It is set forListbox<T>of anyT, and draws every form.
Data List
Section titled “Data List”Terms with their values: what a thing is, item by item. The details of a build, of an order, of a file.
use lurq::ui::{Badge, DataList, Orientation};
DataList::new() .text("Version", "0.60.0") .text("Renderer", "wgpu") .text("License", "MIT") .item("Status", Badge::new("Stable").variant("success"));
// Each term over its value, for a narrow column.DataList::new().orientation(Orientation::Vertical).text("Ship to", "Ivan Zaida, 12 Khreshchatyk St, Kyiv");| Builder | |
|---|---|
text(term, value) | An item whose value is a text, in the value’s type |
item(term, element) | An item whose value is what the app puts there: a badge, a link, tags |
texts(items), items(items) | Several of them at once, from (term, value) pairs |
orientation(Orientation) | Horizontal (the default), each term beside its value, or Vertical, each over it. DataListOrientation is Orientation |
align(Alignment) | How a term and its value stand to each other across: Center (the default), the term centred on its value’s height; Start, the term at the top of its value, where values wrap onto several lines or are elements of several lines |
label(&str) | What the list is called, to what reads the tree |
state(name, on), style(part, ..), rules(&recipe), id, key | As a button has them |
- Side by side, the terms are one column as wide as the widest of them and the values the column of the rest of the width (a grid of two columns,
AutoandFr(1.0)); a line runs under each item but the last, the term’s and the value’s meeting. One over the other, each item is a column. - To what reads the tree each term is a
termand each value itsdefinition. - Parts:
DataListPart::Root,Item(an item one over the other),Term,Value. States:DataListState::HorizontalandVertical(one of them is on),Separator(of an item’s parts: a line under it). - In the design each term and its value are 10 from the lines over and under them and 12 apart, both in the body’s type at 13, the term in
MutedForegroundand the value inForeground; the line is 1 inBorder. One over the other the term is 12, 2 over its value. - A theme’s renderer is given
DataListView:view.items(each a term with its text or its element),view.orientation,view.align,view.idandview.key,view.term(item, lined),view.value(item, lined)andview.render(). A root it builds with no id of its own is given the list’s: the tests and the tooling that find the list by its id find it whatever the theme.
Timeline
Section titled “Timeline”What happened, in its order: the releases of a project, the history of a deploy, the tracking of an order, the activity of a document, a log.
use lurq::ui::{Avatar, Button, Card, Orientation, Timeline, TimelineAlign, TimelineItem, TimelineSize, TimelineVariant};
Timeline::new([ TimelineItem::new("Released 0.60").description("Blur and frosted glass land in the renderer.").time("Nov 10"), TimelineItem::new("Merged node-blur").description("Blurs follow transforms and rounded clips.").time("Nov 8"), TimelineItem::new("Opened pull request").time("Nov 3").upcoming(true),]).label("History");
// A deploy: an icon for each mark, in the item's tone; the current item running.Timeline::new([ TimelineItem::new("Built").icon("box").variant(TimelineVariant::Success), TimelineItem::new("Tests failed").icon("close").variant(TimelineVariant::Destructive), TimelineItem::new("Retrying").pending(true).current(true), TimelineItem::new("Deploy").upcoming(true),]);
// Activity: an avatar for the mark, a comment under the item, an action at its end.TimelineItem::new("Olena Koval commented") .media(Avatar::new("Olena Koval").size("xs")) .time("2 hours ago") .child(Card::new().child(comment)) .action(Button::new("Reply"));
// An order's steps across, each told by its value when it is pressed.Timeline::new([TimelineItem::new("Ordered").value(1u32), TimelineItem::new("Shipped").value(2)]) .orientation(Orientation::Horizontal) .on_select(|step: &u32| open_step(*step));
// A log: small, the times in a column, the history loaded a page at a time.Timeline::new(entries) .size(TimelineSize::Sm) .align(TimelineAlign::TimeColumn) .on_load_more(move || fetch_next_page()) .loading(fetching);| Builder | |
|---|---|
Timeline::new(items) | The items, the first at the top or the start; item(item) and items(items) add more. Timeline<T> holds items of TimelineItem<T>, () unless they have a value |
orientation(Orientation) | Vertical, the board’s: one under another, the line down. Horizontal: side by side, the line across, each item’s text under its mark |
size(impl Into<Name>) | A TimelineSize: Md, the board’s, or Sm, a log |
align(TimelineAlign) | Where the text stands: Start, after the line (the board’s); Alternate, on either side of it item by item; TimeColumn, the time in a column of its own before the line, over it across |
on_select(Fn(&T)) | Told the value of the item pressed, after the item’s own handlers: every item that is not disabled is then pressed. A second handler is called after the first |
on_load_more(Fn()), loading(bool) | An item at the end that shows more, which the line runs on to: its button calls the handler, and while loading its mark is a spinner and it takes no press. The app stops giving on_load_more once it has loaded everything |
more_label(&str), loading_text(&str) | What that button says, “Show more” and “Loading” when not given |
label(&str) | What the timeline is called, to what reads the tree |
state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. force draws the first item that is pressed |
mount(ctx) | In place of building it: a component that reads its own room, so that alternate sides fold to one where it is given less than Timeline::ALTERNATE_LEAST (480) across. It takes the width of what holds it. Its value is to be Clone |
TimelineItem::new(&str) | What happened: its title |
value(T) | What the timeline’s on_select is told when the item is pressed: the id of the event, of the commit, of the step |
description(&str), time(&str) | The text under the title, and when it happened as the app writes it (“Nov 10”, “2 hours ago”): under the description, beside the title in the small size, or apart where the timeline’s align puts it |
icon(name), media(element) | In place of the dot: an icon in a well, or the app’s mark, an avatar |
variant(impl Into<Name>) | A TimelineVariant (Neutral, Info, Success, Warning, Destructive), or a variant a theme adds: the color of the mark. One that failed is Destructive |
current(bool), upcoming(bool), pending(bool) | The one that is now, its mark ringed; one to come, its dot hollow; one running, a spinner for its mark |
child(..), children(..) | Content under the time: a card, a comment, a list of files |
action(element) | The one action, at the end of the item beside what is pressed; a second takes the place of the first |
on_select(Fn()) | The item is pressed: a press, Enter or Space calls it, before the timeline’s handler. A second handler is called after the first |
disabled(bool), id, key | An item that is pressed takes nothing, faded and passed by the keys |
- Each item is its rail beside its content. The rail is the mark over a line that runs to the next item’s mark: the line is as long as the item, so a title or a description that wraps, or content under the time, makes it longer. The last item has no line and no room under its content, unless the timeline shows more, whose item is then the last.
- The titles and the descriptions wrap in the room the rail, the other side and the action leave them; the action keeps its room at the end of the item, beside what is pressed and never in it.
- A timeline is read, not operated, but where an item is pressed (its own
on_select, or the timeline’s) the pressed items are one stop of Tab, a focus group that isone_stop, withtypeaheadand withoutwrap: Up and Down move between them (Left and Right across), Home and End go to the first and the last, a letter to the next title it starts, and a disabled item is passed by. An item’s action is a stop of its own. - Across, the items share the width, each at least 160 (120 small), and wrap their text in it; a timeline wider than its room scrolls sideways in a scroll area that fills its width (
ScrollArea::fill_width), and the keys bring the focused item into view. Across, the text is under the marks, and the time column is a line over them; alternate sides are drawn down only. - Alternate sides need room. Mounted with
mount(ctx), a timeline measures the room it is given and folds them to one side, asStartdraws it, where that is less thanTimeline::ALTERNATE_LEAST, 480: in a narrow panel of a wide window too. It measures withElementRef::observe_rect_before_paint, so the frame that lays it out shows the form that fits, from its first frame and as a splitter’s divider drags its pane across that width. Built as an element of its own (converted withinto(), or built by another component’s renderer) it has no room of its own to read, and folds them in a window narrower than the theme’smdbreakpoint, 768 by default. - A long history is loaded a page at a time, as a feed is:
on_load_moreandloading, with the app appending what comes. It is not in a virtual list: a timeline stands in the page and scrolls with it, where a virtual list needs a box of its own, and its items hold the app’s elements (a card, a comment). Every item it holds is built. - The small size is a log: its items are rows, as high as the theme’s density makes a row of 28 at the least (20, 36 and 40 at compact, comfortable and touch); the board’s size is not a row and keeps its height.
- To what reads the tree it is a
listcalled by its label, oflistitems called by their titles and described by their descriptions; the current one saysa11y_current, a pending onea11y_busy, and inside an item that is pressed is abutton. The item that shows more is alistitemwith its button, busy while it loads. - Parts:
TimelinePart::Root(the list),Item,Rail,Dot,Mark(the well of an icon, what holds the media, the spinner),Icon,Separator(the line),Content(the title, the description, the time and the body),Header(the title, and the time beside it in the small size),Title,Description,Time,Body,Action(at the end of the item),Opposite(the side of the line the time stands on where it is apart),More(the button that shows more). States of the timeline:TimelineState::VerticalandHorizontal(one is on),Start,AlternateandTimeColumn(one is on, as the timeline is laid out),Mark(an item has an icon or media); of an item:Before(its text is before the line),Current,Upcoming,Pending,Last,Icon,Media,Pressable,Disabled; of the item that shows more:More,Loading. Sizes:TimelineSize::Sm,Md. - In the design an item’s rail is 12 and its content 12 from it. The rail is 4 down to a dot of 10 in
Primaryand, 4 under it, a line of 1 inBorder. The title is the body’s type at 14 at 500 inForeground, the description 13 inMutedForegroundwith lines 1.4 high, the time the mono type at 11 inMutedForeground, 2 apart, with 20 under them. The board’s last item has a hollow dot,Backgroundwith an edge of 1.5 inInputinside it. - The board draws nothing else of it, and these follow its parts: a tone colors the dot (
Primary,Info,Success,Warning,Destructive), and the edge of a hollow one; the current dot has a ring of 2 in its color, 2 out from it; an icon is 14 in a well of 24 onMuted, in the tone’s color; media stands in a mark of 24, and every rail of a timeline with a mark is 24 wide, its line stopping 4 over the next mark; a pending item’s mark is a spinner of 12; the mark of a current item is ringed as its dot would be, and the well of an upcoming one is hollow. A body is 8 under the time. An item that is pressed has theStateHoverandStatePressedveils and a ring of 2 inRinginside it, with the medium radius, and is half opaque where it is disabled. - The small size: a dot of 8 on a rail of 8, 10 from the content, the title 13 with the time at the end of its row, the description 12, 4 under the content; a mark is 20, its icon 12. The time column is 80 (64 small), its time at its end, 2 down to stand by the title. Alternate, the two sides share the room, the text before the line at its end. Across, the rail is a row 12 high (10 small, 24 with marks), its mark in its middle and its line 4 short of the next mark, the content 8 under it (6 small) and 12 from the next item. The item that shows more is a small ghost button, its hollow dot in the middle of it.
- A theme’s renderer is given
TimelineView:view.items(each aTimelineItemViewwith its title, description, time, whether it is current, pending, the last and before the line, anditem.mark(),item.rail(),item.content(),item.opposite(),item.action(),item.root(children),item.render()),view.more(aTimelineMorewithmore.mark(),more.button(),more.render()),view.horizontal,view.groupedandview.root(items).
Bar List
Section titled “Bar List”Named values as bars of one scale: the slowest tests of a run, the largest folders, the pages visited most.
use lurq::ui::{BarList, BarListItem};
BarList::new([("text_pipeline", 9.2), ("canvas_mesh", 7.0), ("layout_flex", 4.7), ("theme_roles", 2.5)]) .title("Slowest tests") .description("Seconds");
// Rows that are pressed, told which by name: one stop of Tab, the arrows between them.BarList::new([BarListItem::new("target/", 27.4), BarListItem::new("node_modules/", 3.1)]) .title("Largest folders") .value_text(|gigabytes| format!("{gigabytes:.1} GB")) .on_select(|folder| open(folder));| Builder | |
|---|---|
BarList::new(items) | The rows in the app’s order: BarListItem::new(name, value) or (name, value); item(..) and items(..) add more |
title(&str), description(&str) | Over the rows: what they are, and the line under it (“Seconds”) |
label(&str) | What the list is called to tooling, where it has no title or another name is wanted |
max(impl Into<f64>) | The value a bar fills its track at. Not given, the largest value rounded up to 1, 2, 2.5 or 5 of a power of ten |
color(impl Into<BackgroundColor>) | The color of the bars, a role of the palette or a color as a chart’s series takes it: Chart1 (series_color(0)) unless given; BarListItem::color for one row’s |
value_text(Fn(f64) -> String) | Writes a row’s value as the app does. Not given, with as many decimals as the most precise value has, up to 2 |
empty_text(&str) | What a list with no rows says, “No data” when not given |
framed(bool) | The board’s card, as it is unless told otherwise; off, the rows stand on what holds them |
on_select(Fn(&str)) | Told the key of the row pressed (its name, unless it has a key), after the row’s own handlers: every row that is not disabled is then pressed |
state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. force draws the first row that is pressed |
BarListItem::on_select(Fn()), disabled(bool), key(..), id(..), color(..) | A row’s own handler, called before the list’s; a row that takes nothing; what the list’s on_select is told in its place |
- The bars share one scale, from 0 to
max: 9.2 of a scale to 10 fills 92% of its track. A value under 0 draws no bar, and one over the scale fills its track; the value is written as it is either way. - A name longer than its column of 92 is cut with an ellipsis; the track gives way, the value keeps its room.
- A row is as high as the theme’s density makes a row of 26 (18, 34 and 38 at compact, comfortable and touch); its bar keeps its 14.
- It is read and not operated, but where a row is pressed the pressed rows are one stop of Tab, a focus group that is
one_stop, withtypeahead: Up and Down move between them, Home and End to the ends, a letter to the next name it starts, and a disabled row is passed by. - To what reads the tree it is a
figurecalled by its label or its title and described by its description, holding alistwhoselistitems are called by their names and say their value asa11y_valuetext; inside a row that is pressed is abutton. - Parts:
BarListPart::Root,Header,Title,Description,Rows,Row,Name,Track,Bar,Value,Empty. States:BarListState::Framed(of the list), and of a rowPressable,Disabled. - In the design the list is a card (
Cardwith an edge of 1 inBorder, the extra large radius and the small shadow), 20 in, its header and its rows 16 apart. The title is 15 at 600 inCardForegroundover the description, 12 inMutedForeground, 3 under it. A row is its name, the mono type at 11 inCardForegroundin a column of 92, a track of 26 with a bar of 14 inChart1and the small radius, and its value, the mono type at 11 inMutedForeground, 10 apart. The board draws nothing else of it: a row that is pressed has theStateHoverandStatePressedveils and a ring of 2 inRinginside it, and is half opaque where it is disabled. - A theme’s renderer is given
BarListView:view.rows(each aBarListRowwith its name, value, value text, the share of its track and its color, androw.name(),row.track(),row.value(),row.root(children),row.render()),view.max,view.header(),view.rows(rows)andview.root(content).
Sparkline
Section titled “Sparkline”A series as a line with no axes, small enough to stand beside a number: the frames of the last minute, the builds of the week. It is drawn on the canvas, behind the canvas feature.
use lurq::{app::theme::PaletteColor, ui::Sparkline};
Sparkline::new([118.0, 124.0, 121.0, 133.0, 129.0, 141.0, 138.0, 144.0]) .color(PaletteColor::Success) .label("Frames per second, the last minute");| Builder | |
|---|---|
Sparkline::new(values) | The values, impl Into<f64>, the first at the start |
min(..), max(..) | The values at the bottom and at the top: the least and the greatest of the values unless given |
color(impl Into<BackgroundColor>) | The color of the line, a role of the palette or a color as a chart’s series takes it: Chart1 (series_color(0)) unless given, or a tone where the series is good or bad (the board’s frames are Success) |
width(..), height(..) | Its size, impl Into<Length>: the board’s 80 by 28 unless given |
label(&str) | What it shows, to tooling |
summary_text(Fn(&[f64]) -> String) | What its values are, to tooling. Not given, “8 values from 118 to 144, the last 144” |
empty_text(&str) | What a sparkline of no values says to tooling, “No data” when not given |
state(name, on), style(part, ..), rules(&recipe), id, key | As a button has them |
- Its values run from the first at the start to the last at the end, evenly apart, the least at the bottom and the greatest at the top, as a line of straight steps with round joins and ends, kept half its width in from every edge.
- Values on both sides of 0 have a line at 0 under them; values all the same make a line across the middle; one value is a dot in the middle; none draw nothing. A value that is not a number is left out.
- It is painted with
Canvas::paint: sharp at every scale, and painted again when its values, its size, its scale or the theme change. - To what reads the tree it is an
imgcalled by its label and described by its summary, and its canvas holds apointitem for each value with the value as its text, which a reader can go through. - Parts:
SparklinePart::Root(the canvas: its width and height),Line,Baseline,Point, each drawn in its part’s background and as wide as its part’s width. - In the design the line is 80 by 28 of straight steps, 1.75 wide with round joins and ends. The board draws nothing else of it: the line at 0 is 1 in
Border, and a single value a dot of 4 inChart1. - A theme’s renderer is given
SparklineView: its values, their range, its label, its summary, andview.render().
Stat Card
Section titled “Stat Card”One number with what it is and how it moved: frames per second, the time a build takes, the runs that failed.
use lurq::{ app::theme::PaletteColor, ui::{Sparkline, StatCard, StatCardSize, StatCardVariant},};
StatCard::new("Frames per second", "144") .delta("+12.5%") .variant(StatCardVariant::Success) .description("vs 0.59");
// With a sparkline beside its number, in the small size the board draws it in.StatCard::new("Frames per second", "144") .size(StatCardSize::Sm) .media(Sparkline::new(frames).color(PaletteColor::Success));| Builder | |
|---|---|
StatCard::new(label, value) | What the number is, and the number as the app writes it |
delta(&str) | How it moved, as the app writes it (“+12.5%”): a badge in the variant’s tone |
variant(impl Into<Name>) | A StatCardVariant (Neutral, Info, Success, Warning, Destructive), or a variant a theme adds: whether the change is for the better or the worse |
description(&str) | What the change is measured against: “vs 0.59” |
media(impl Into<Element>) | What stands at the end of the number’s row: a sparkline of its last values |
size(impl Into<Name>) | A StatCardSize: Md, the board’s stat card, or Sm, the card the board draws around its sparkline |
on_click(impl IntoMouseEventHandler) | The card is pressed and a stop of Tab; a second handler is called after the first |
state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them |
- Its number, its change and what it is measured against are the app’s words. A label or a value longer than the card wraps.
- To what reads the tree it is a
groupcalled by its label and described by its value, its change and what it is measured against (“144, +12.5% vs 0.59”); a card that is pressed is abutton. - Parts:
StatCardPart::Root,Label,Body(the value and the media),Value,Media,Footer(the change and the description),Description. States:StatCardState::Pressable,Media. Sizes:StatCardSize::Sm,Md. - In the design the card is
Cardwith an edge of 1 inBorder, the extra large radius and the small shadow, 200 on the board and as wide as what holds it here, 20 in, its label, its value and its change 8 apart. The label is 13 inMutedForeground, the value 28 at 600 inCardForeground, 0.5 closer, the change a badge in its tone 8 from what it is measured against, the mono type at 11 inMutedForeground. The small size is the card around the board’s sparkline: 16 in, the label 12, the value 24, 0.4 closer, the media at the end of the value’s row, at its foot. A card that is pressed has theRingedge and the medium shadow under the pointer, and a ring of 2 inRingaround it from the keyboard. - A theme’s renderer is given
StatCardView: its label, value, change, description and tone,view.label(),view.body(),view.footer(),view.root(content)andview.render().
A video player, an audio player and the parts they are built of. Given a source (source(&Source), with the
feature media), a player plays it with the system’s decoder and output and its controls move it; without one,
every value it shows is the app’s, bound to its signals or held by it, and what a person does is told back. A
player, a queue, a seek bar and a volume control keep a drag, a measure of their room or a menu between renders:
each is a component, mounted with .mount(ctx) or declared where an element goes (.child(player)).
Video Player
Section titled “Video Player”A picture the app gives, the controls over it, and a layer of the app’s own over the picture: an ordinary player, or only the picture with the app’s own controls, as in a vertical feed. Nothing is decoded here: the app draws its frame as an element and holds every value of the player; the player tells it what a person asks for.
use lurq::ui::{VideoPlayer, VideoPlayerSize};
// Bound to the app's signals: a press sets the signal, and then the handlers are told.VideoPlayer::new() .media(frame) .duration(250.0) .buffered(140.0) .playing(playing.clone()) .position(position.clone()) .volume(volume.clone()) .muted(muted.clone()) .preview(move |at| thumbnails.frame_at(at)) .on_position_change_end(move |to| decoder.seek(to)) .mount(ctx);
// Held by the app: a press changes nothing until the app answers by setting the prop.VideoPlayer::new() .media(frame) .duration(250.0) .playing_controlled(is_playing, move |play| decoder.set_playing(play)) .position_controlled(at, move |to| decoder.seek(to));
// The picture alone, with the app's own controls over it.VideoPlayer::new().media(frame).controls(false).child(my_controls).mount(ctx);| Builder | |
|---|---|
new() | A player of nothing yet: a black picture, paused at the start, of no known length |
media(element) | What is drawn as the picture, filling the player |
poster(element) | Drawn over the picture before the first play (not playing, at the start, not waiting, ended or failed), with the length in a chip at its bottom end and no bar. With a source it also stays until the video’s first frame is there, whether or not it was told to play already. Nothing of the picture is drawn under it: a poster that does not cover the box shows the box beside it |
poster_until_frame(bool) | Whether the poster stands only until the source has a frame of its own to show, also where it has not played yet; false unless told. A video opened ahead and left paused then shows its first frame, the picture it plays on from, and its poster only while that frame is still to come. The poster stays over a source with no picture (a sound). A player without a source is as without it |
child(element), children(..) | The app’s own layer over the whole picture, under the middle and the bar, with the controls and without them |
child_with(Fn(&VideoPlayback) -> element) | A layer of the app’s built from what the player is doing each time it is rendered: position, duration, buffered, playing, waiting, ended, failed, opening, poster_shown, volume, muted, rate, progress(), and seek(seconds), set_playing(bool), set_muted(bool) to move it. How an app’s own controls show and set the time of a player with a source: see your own controls |
background(color) | What is behind the picture, where the picture does not cover the box: beside a video of another shape, and before its first frame. Black unless told; a clear color shows what the app has under the player. The same as `style(VideoPlayerPart::Root, |
controls(bool) | The bar and the middle of the picture; on by default. Without them the player is its picture and the app’s layer |
playing(Signal<bool>), playing_controlled(bool, handler), on_playing_change(handler) | Whether it plays. Play, the disc in the middle, a press of the picture, Space and K tell what it is to be |
position(Signal<f32>), position_controlled(f64, handler), on_position_change(handler), on_position_change_end(handler) | Where it is, in seconds. on_position_change is told as the seek bar’s handle moves, on_position_change_end where it is let go; a key that seeks tells both |
duration(f64), buffered(f64), chapters(&[f64]) | How long it is (until said, the time reads -:-- / -:--), how far it is loaded, and where its chapters start. With a source the player knows how far unless told (MediaState::buffered): all of a file, of bytes and of a sound loaded whole; of an address the app’s loader reads as it plays (Windows), the end of the ranges it holds in a row from where it plays, by the share of its bytes, which grows as ranges come and is no further than the position after a seek to a part not fetched; and nothing is drawn as loaded where it is not known (before it opened, and an address the system’s own player reads: macOS, iOS, a browser). It was the whole length from the moment it opened |
preview(Fn(f64) -> Element) | The frame for a time, which the mounted seek bar shows in a frame of 128 by 72 over the time under the pointer |
volume(Signal<f32>), volume_controlled(f64, handler), on_volume_change(handler), on_volume_change_end(handler) | How loud, from 0 to 1 |
muted(Signal<bool>), muted_controlled(bool, handler), on_muted_change(handler) | Whether the sound is off; the volume is kept |
rate(Signal<f32>), rate_controlled(f64, handler), on_rate_change(handler), rates(&[f32]) | How fast it plays, and the speeds offered (MEDIA_RATES unless told) |
captions(Signal<bool>), captions_controlled(bool, handler), on_captions_change(handler) | Whether the captions show |
caption_text(&str), captions_track(&str) | The line to show now, and the name of the track the settings say (“English”) |
captions_button(bool), settings_button(bool) | Whether the captions’ button (with their row in the menus and the key C) and the settings’ button (with its menu) are drawn: they are unless told. The captions’ button is drawn only where the player has captions, whatever this says: a track (caption_cues, captions_track), a line (caption_text), captions the app holds (captions, on_captions_change) or that are on. The settings’ button only where its menu has something in it: qualities, a speed (not live), captions. Without the settings the large form keeps its speed’s button; the compact form has none, and its “more” menu stays |
looped(bool) | Its source goes on from its start at its end, as a clip in a feed does: in what it has open, with nothing opened or read again. on_ended is told each time round, playing stays true and the player is not drawn as ended. Off unless told; a player without a source does nothing with it |
qualities(&[&str]), quality(Signal<Option<usize>>), quality_controlled(..), on_quality_change(handler) | The qualities offered after “Auto”, and the one it plays in: None for the one the player picks |
fullscreen(Signal<bool>), fullscreen_controlled(..), on_fullscreen_change(handler) | Whether it fills the screen; its button then exits. The app makes it so |
picture_in_picture(Signal<bool>), picture_in_picture_controlled(..), on_picture_in_picture_change(handler) | Whether it plays in a small window of its own |
waiting(bool) | It waits for what it plays: a spinner in the middle, and the bar stays |
ended(bool) | It played to the end: the veil, replay in the middle and in the bar, the seek bar full. Replay tells playing true: the app plays again from the start |
live(bool) | No end: the LIVE badge for the time, the seek bar full (or the window that can be gone back in, given as the duration), no speed |
error(&str), error_description(&str), on_retry(handler) | That it cannot play: the veil, the title and the line in the middle, and no bar. The button (“Try again”) is drawn once on_retry is given |
on_load(Fn(&MediaInfo)), on_error(Fn(&MediaError)), on_started(Fn()), on_ended(Fn()), on_waiting_change(Fn(bool)) | What its source tells: it opened (its length, its picture’s size, whether it has sound), it cannot play (a kind, which the locale says under the error’s title), it really started to play (the first frame after it was told to is shown), it played to its end, it began or stopped waiting. A player without a source is told none of them |
size(VideoPlayerSize) | Lg, Md (compact) or Sm (minimal) in place of the form its width gives it |
width(Length), height(Length) | Its size, in place of its form’s (640 by 360 for the large one). A width with no height gives the height its aspect makes |
caption_cues(&MediaCaptions) | A track of captions: while they are on, the player shows what the track says at its position. caption_text given too is shown in its place |
fullscreen_fills(VideoFullscreen) | What a mounted player in fullscreen fills: its window as it is (Window, the default); its window taken to the whole screen (Screen); nothing, where the app lays it out itself (App) |
picture_in_picture_window(bool) | Whether a mounted player in picture in picture opens its small window itself (the default). Without it the value is told and drawn, and the window is the app’s |
in_picture_text(&str), back_label(&str) | What stands where the player was while it is in its small window, and the button that brings it back |
touch(bool) | The touch form: larger controls over a scrim, shown and hidden by a tap; two taps on a side third seek ten seconds, and more add up. On its side while in fullscreen. Unless told, the touch form under a finger, Pointer::Coarse (the touch form), whatever its width and the density |
title(&str), description(&str) | What plays and a line under it, at the top of the touch form on its side |
on_back(impl Fn()) | The first button of the touch form’s top row: drawn upright where a handler is given, always on its side, where it leaves fullscreen if there is none |
max_width(Length) | The most it is wide: narrower where what holds it is, its aspect kept |
aspect(f32) | The shape of the picture, its width over its height: 16.0 / 9.0 unless told |
force_menu(Option<VideoPlayerMenu>), force_controls_shown(Option<bool>) | A menu drawn open, or the bar shown or faded, with nothing pointing at it: for a gallery or a test |
label, play_label, pause_label, replay_label, mute_label, unmute_label, volume_label, seek_label, captions_label, speed_label, settings_label, quality_label, picture_in_picture_label, fullscreen_label, exit_fullscreen_label, more_label, retry_label, speed_heading_text, auto_text, on_text, off_text, live_text | Every word it says and every name it gives a control |
state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. force draws the buttons of the bar as under the pointer or focused. The controls have ids after the player’s: {id}-play, {id}-seek, {id}-mute, {id}-time, {id}-captions, {id}-speed, {id}-settings, {id}-pip, {id}-fullscreen, {id}-more, {id}-center, {id}-retry, {id}-controls, {id}-caption, {id}-overlay, and the menus’ panels {id}-settings-menu, {id}-speed-menu, {id}-more-menu |
mount(ctx) | Keeps its width, the timer that fades the bar, its menus and their pages, the seek bar’s preview and its tooltips. .child(player) is the same component, declared: what renders the tree mounts it |
build(theme) | A still picture for a test or a screenshot: the bar shown, the large form unless told or given a width in pixels, its menus not opened, no tooltips and no preview |
- A press on a control tells the app what the value is to be and changes nothing by itself: bound, the signal is set first; held, the app answers with the next render. No handler is called when the app sets a value, nor for a choice of what is already chosen.
- Forms. The large form has the seek bar over a row of play, the volume (its slider folds into its button under 480), the time, then captions (where it has them), the speed (“1×”), settings, picture in picture and fullscreen. The compact form, under 400 wide, has play, the time, mute, a “more” menu of captions (where it has them), speed, quality and picture in picture, and fullscreen. The minimal form, under 280, is one row: play, the seek bar and the elapsed time. Mounted, the form follows the width it is laid out at from the first frame (
ElementRef::observe_rect_before_paint);sizesays another.VideoPlayerSize::for_widthgives the form of a width, andVIDEO_PLAYER_COMPACT_BELOW,VIDEO_PLAYER_MINIMAL_BELOWandVIDEO_PLAYER_VOLUME_FOLDS_BELOWare the widths. - Layers, bottom to top: the picture (and the poster), the veil, the app’s layer, the middle (the 64 overlay play button while paused, 48 in the compact form; a spinner while it waits; replay when it ended; the error), the captions’ line, the poster’s length, and the bar on its gradient. A press of the picture plays and pauses at once; a second press within
VIDEO_PLAYER_DOUBLE_PRESS(500 ms) asks for fullscreen too. The app’s layer and the middle let a press through where they hold nothing. - Hiding. While it plays the bar fades out
VIDEO_PLAYER_HIDE_AFTER(3 s) after the pointer rests, over the slow duration, and the pointer is hidden over the player (CursorIcon::None); both come back on a move of the pointer, on pause, while the keyboard’s focus is in the player and while a menu is open, over the base duration. Paused, waiting, ended and failed keep them. The captions’ line moves down to 12 over the bottom while the bar is hidden. - Keys, while the focus is in the player: Space and K play and pause, Left and Right seek 5 s (
VIDEO_PLAYER_SEEK_STEP), J and L 10 s, Home and End go to the start and the end, Up and Down move the volume by 0.05, M mutes, C turns the captions (where it has them), F asks for fullscreen. Space and the arrows are the controls’ own while the keyboard’s focus is on one of them. A press of the picture gives the player the focus. - Menus. Settings holds Quality (when
qualitiesare given), Speed (not live) and Captions (where it has them), each with its value at its end; choosing a row shows its choices in the menu’s place under a row that goes back (the menu’s pages), and choosing one closes the menu. The speed button opensui::MediaSpeedMenu; the compact form’s “more” holds captions, speed and quality (each with its page) and picture in picture. They hang over the seek bar, their end on the bar’s end, and stay the theme’s. - Seeking with a preview. Mounted, the seek bar shows the time under the pointer and, where
previewis given, the frame for it over the time (Media/Seek Preview). - Everything over the picture is white on black at the board’s alphas, the same in a light and a dark theme: the picture is not themed, so themed controls would lose their contrast on it. The literals are in the recipe. The menus, the tooltips and the live badge are the theme’s.
- Every control has a tooltip with its key (mounted) and a name to what reads the tree; the toggles say
a11y_pressed, the menu buttonsa11y_haspopupanda11y_expanded. The player is agroupcalled by its label. - Parts:
VideoPlayerPart::Root,Media(the picture’s layer; its cursor is the pointer’s while it is pressed to play),Veil,Overlay,Center,Spinner,Error,ErrorIcon,Text,Title,Description,Retry,Captions,Caption,Chip,ChipValue,Controls(its background is the color its gradient ends in),Row,Control,ControlIcon,Speed,Time,Elapsed,Menus(its gap is how far a menu stands over the row),SettingsMenu,MoreMenu,MenuValue. States:VideoPlayerState::Playing,Waiting,Ended,Error,Live,Muted,Captions,Fullscreen,Poster,Bare,Hidden,Narrow, andOn, resolved for a button of the bar that is on, under the pointer too. Sizes:VideoPlayerSize::Sm,Md,Lg. - In the design (
Video PlayeryKk3P,Compactcak7v,MinimalOUkUD) the large player is 640 by 360 with the large radius. Its bar is 88 high, padded 24 at the top, 12 at the sides and 8 at the bottom, 4 between the seek bar and the row, on a gradient from nothing to#000000B3; the row is 36 high, 4 between buttons of 36 with white glyphs of 20, the middle radius,#FFFFFF1Funder the pointer,#FFFFFF33while on, and a white ring of 2 from the keyboard. The time is mono 12 in the large bar and 11 in the compact one. The compact bar is 72 high, padded 20 8 6, a row of 28 with 2 between buttons of 28 and glyphs of 16; the minimal one is a row 48 high padded 16 8 4 4, 6 apart. The settings are 240 wide, the compact menu 200. The captions’ line is 12 over the bar and 24 from the sides, 16/500 white with a line of 1.4 in a box of#000000B3padded 2 8. The poster’s length is mono 11 in a box of#000000B3padded 2 6, 12 from the bottom and the end. The veil is#00000099. The error is a white glyph of 24, a title 14/500, a line 13 in#FFFFFF99, and a white button 32 high. - A renderer that draws another player starts from the view:
view.root()(the box with its behavior),media(),veil(),overlay(),center(),captions(),chip(),bar(), orview.barfor the controls made (VideoPlayerBar: the seek bar, play, the volume, the time, the buttons at the end and the menus).
Audio Player
Section titled “Audio Player”Sound without a picture, in four forms: a full card, one row of 48 for a list or a message, a voice message, and a mini player docked to the bottom of a window. Every value is the app’s; a press of a control tells the app what it is to be and changes nothing by itself.
use lurq::ui::{AudioPlayer, AudioPlayerVariant, AudioRepeat};
// The card, bound to the app's signals: a press of play sets `playing`, a drag on the bar sets `position`.AudioPlayer::new(position.clone(), 250.0) .title("Night Drive") .description("Aurora Lane · Low Tide") .media(artwork) .playing(playing.clone()) .volume(volume.clone()) .muted(muted.clone()) .rate(rate.clone()) .shuffle(shuffle.clone()) .repeat(repeat.clone()) .on_previous(|| previous()) .on_next(|| next()) .mount(ctx);
// A voice message: the app holds where it is and seeks where the waveform is let go.AudioPlayer::controlled(17.0, 42.0, |_| {}) .variant(AudioPlayerVariant::Voice) .peaks(&peaks) .unheard(!heard) .playing_controlled(false, move |play| player.set_playing(play)) .on_change_end(move |to| player.seek(to)) .mount(ctx);| Builder | |
|---|---|
new(Signal<f32>, duration) | Bound to the position, in seconds, of something duration seconds long. A drag on the bar sets the signal |
controlled(position, duration, on_change) | The position held by the app, which is told where a person moves it |
variant(AudioPlayerVariant) | Full (the card, the default), Compact, Voice, Mini |
on_change(Fn(f64)), on_change_end(Fn(f64)) | Where a person moves the position, as a drag moves it and where it is let go, a key’s step is made or the mini player’s line is pressed |
buffered(f64) | How far it is loaded, in seconds. With a source the player knows it unless told, as a video player does: all of a sound loaded whole or kept, the ranges fetched of one read as it plays, nothing where it is not known |
playing(Signal<bool>), playing_controlled(bool, handler), on_playing_change(Fn(bool)) | Whether it plays. A press of play, or Space with the focus on the bar or the volume, tells what it is to be |
volume(Signal<f32>), volume_controlled(f64, handler), on_volume_change(Fn(f64)) | The volume, from 0 to 1: the card and the mini player |
muted(Signal<bool>), muted_controlled(bool, handler), on_muted_change(Fn(bool)) | Whether it is muted; muting keeps the volume |
rate(Signal<f32>), rate_controlled(f64, handler), on_rate_change(Fn(f64)) | The speed: the card’s speed button opens MediaSpeedMenu; a voice message’s badge steps 1×, 1.5×, 2× (VOICE_RATES) while it plays |
shuffle(Signal<bool>), shuffle_controlled(bool, handler), on_shuffle_change(Fn(bool)) | Shuffle, in the card |
repeat(Signal<AudioRepeat>), repeat_controlled(AudioRepeat, handler), on_repeat_change(Fn(AudioRepeat)) | Off, All, One; a press steps it (AudioRepeat::next), and One has the repeat-one glyph |
source(&Source) (feature media) | What it plays: a file, bytes, a resource of the app, an address. The player opens it as a sound and plays it; where it is, how long it is and whether it plays, loads or failed are then the sound’s, and its controls move it. An address is loaded when it is first played, once, and kept (media::sound_cache()). See media-playback.md |
on_load(Fn(&MediaInfo)), on_error(Fn(&MediaError)), on_started(Fn()), on_ended(Fn()), on_waiting_change(Fn(bool)) | What its source tells, as a video player’s: it opened (its length; a sound has no picture’s size), it cannot play (a kind, which the locale says in its line), it played to its end (each end of a track that repeats; where a queue goes on to the next), it began or stopped waiting. With a source on_playing_change hears the sound stop and start by itself too. A player without a source is told none of them |
loading(bool) | Lines of skeleton for the texts, ”-:—” for the times, an empty bar, a spinner in play, previous and next dimmed |
error(Option<&str>), on_retry(Fn()), retry_text(&str) | What went wrong: a line in the destructive color in place of the times (in place of the bar in a row, where play turns to a retry button; in place of the description in the mini player). “Try again” at its end in the card |
unheard(bool) | A voice message not heard yet: a dot of 8 in the info color, and the whole waveform in the color of what is not played |
title(&str), description(&str), media(element) | What plays, who it is by, and the artwork (64 in the card, 36 in the mini player); the music glyph on Muted where there is none |
peaks(&[f32]) | The loudness of each bar of a waveform, from 0 to 1: a voice message draws it, the compact row in place of the bar |
on_previous, on_next, on_more, on_queue, on_expand | Commands; each call adds a handler. more_anchor(ElementRef) is the ref of the card’s more button, for a menu of the app |
label(&str) and play_label, pause_label, previous_label, next_label, shuffle_label, repeat_label, more_label, speed_label, queue_label, expand_label, seek_label | What the player and its controls are called |
mount(ctx) | The tooltips of the buttons, the speed menu, the mini player’s form from its own width, and the time over the mini player’s line under the pointer. .child(player) is the same component, declared: what renders the tree mounts it |
build(theme) | A still picture for a test or a screenshot: no tooltips, no speed menu, a mini player as wide as it is given |
disabled(bool), state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. force draws the play button; id is the root’s, and each control has it with -play, -seek, -previous, -next, -shuffle, -repeat, -more, -speed, -volume, -queue, -expand, -retry, -rate, -line after it |
- Built of the media parts:
PlayButton,SeekBar,Waveform,MediaTime,MediaVolume,MediaSpeedMenu. Shuffle and repeat areToggles; previous, next, more, queue and expand ghostButtons; “Try again” aLink. - Keys: Tab reaches each control; Space on play presses it, and with the focus on the bar or the volume plays and pauses; the arrows move the bar and the volume.
- The mini player measures itself before its first frame is painted: under 480 wide (
AUDIO_MINI_NARROW) it keeps the track, play and next. - Parts:
AudioPlayerPart::Root,Bar,Edge,Header,Media,MediaIcon,Text,Title,Description,Skeleton,More,Progress,Times,Elapsed,Total,Time,Transport,Shuffle,Repeat,Footer,Speed,Error,ErrorIcon,ErrorText,Retry,Rate,Dot,Track,Fill,Tools. States:AudioPlayerState::Playing,Loading,Error,Disabled,Media,Unheard,Shuffle,Narrow,Scrubbing. - In the design the card is 360 wide on
Cardedged inBorder,radius-xl, padded 20 with 16 between rows; the artwork 64 withradius-md; the title 14/600 and who it is by 13 inMutedForeground; the times mono 11 6 under the bar; the transport 8 apart (shuffle 32, previous 36, play 48, next 36, repeat 32, icons 16); shuffle and repeat inMutedForegroundoff and onHighlighton. The compact row is 320 by 48,radius-lg, padded 8 and 12, 10 apart. The voice message is padded 8 12 8 8,radius-xl. The mini player is onBackgroundwith a line ofBorderon top, under a progress line of 2 (4 under the pointer) inPrimaryoverSecondary, and a row of 54 padded 12. - To what reads the tree the player is a
groupcalled by its label; the error line is analert; the mini player’s line aprogressbar; repeat says its state ina11y_value. - A renderer that draws another player starts from
AudioPlayerView: the controls are built (view.controls), andmedia(),text(),time(),error_line()andline()are the default pieces.
Audio Queue
Section titled “Audio Queue”The tracks a player plays one after another, the one it is on marked. The arrow keys move between the rows.
use lurq::ui::{AudioQueue, AudioQueueItem};
// Bound to the app's current track, which a press of a row sets.AudioQueue::new( current.clone(), [ AudioQueueItem::new("Night Drive").description("Aurora Lane").duration(250.0).media(artwork), AudioQueueItem::new("Paper Boats").description("Mira Sol").duration(232.0), AudioQueueItem::new("Glass Garden").description("The Fernweh").duration(301.0).disabled(true), ],).playing(true).mount(ctx);| Builder | |
|---|---|
new(Signal<Option<usize>>, items) | The tracks, on the one whose index the signal holds, which a press of a row sets |
controlled(Option<usize>, items, on_change) | The current track held by the app, which is told the index of a row pressed |
on_change(Fn(usize)) | The index of a row pressed, where it is another than the current one and can be played. A second handler is called after the first |
playing(bool) | Whether the current track plays: the equalizer glyph stands for its number |
item(AudioQueueItem), items(..) | Adds tracks at the end |
label(&str), more_label(&str), playing_label(&str) | What the queue (“Queue”), a row’s more button (“More”) and the equalizer (“Now playing”) are called |
mount(ctx) | Mounts it at once, with the tooltips of the rows’ more buttons. .child(queue) is a component that has them too |
build(theme) | A still picture for a test or a screenshot: the buttons have no tooltips |
disabled(bool), state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. force draws the row Tab would stop on |
AudioQueueItem | |
|---|---|
new(&str) | A track by its title |
description(&str), media(element), duration(f64) | Who it is by, the artwork (cut to 32; the music glyph on Muted where there is none), and its length in seconds |
disabled(bool) | It cannot be played: half the opacity, a press does nothing, the arrows pass it by |
on_select(Fn()) | Called on a press of the row, after the queue’s on_change |
on_more(Fn()), more_anchor(ElementRef) | The row’s more button, there once a handler is given, and the ref a menu of the app hangs from |
id, key | The id of the row; its more button has it with -more after it |
- Tab enters the queue at the current row (or the first that can be played) and stops in it once; the arrows move between the rows; Enter and Space play one. The more buttons are stops of Tab of their own, after their row, and the arrows do not go to them.
- Parts:
AudioQueuePart::Root,Item,Lead,Number,LeadIcon,Media,MediaIcon,Text,Title,Description,Duration,More. States:AudioQueueState::Current,Playing,Unavailable,Media(on a row’s parts) andDisabled. - In the design a row is 48 high (following the density), padded 8 with 12 between its parts,
radius-md: the number 20 wide in mono 12 inMutedForeground, the artwork 32 withradius-sm, the title 13/500 over who it is by 12, the length in mono 11, a more button of 28 with an icon of 14. The current row is onHighlightwith its title 600; while it plays theequalizer16 stands for its number. Under the pointer the row takes the hover veil,play14 stands for the number and the more button shows; the focus is a ring of 2 inRinginside the row. An unavailable row is at half the opacity. - To what reads the tree the queue is a
listboxcalled by its label, each row anoptioncalled by its title and who it is by,a11y_selectedon the current one.
Seek Bar
Section titled “Seek Bar”Where a player is in what it plays, how much of it is loaded, and the handle that moves it; over the pointer, the time it is on.
use lurq::ui::{SeekBar, SeekBarSize};
// Bound to the app's position, in seconds, of a recording 250 seconds long.SeekBar::new(position.clone(), 250.0) .buffered(loaded) .on_change_end(move |to| player.seek(to)) .mount(ctx);
// Over a video, cut into chapters, with a frame of the moment under the pointer.SeekBar::new(position.clone(), duration) .on_media(true) .chapters(&[0.0, 312.0, 840.0]) .preview(move |time| thumbnail_at(time)) .mount(ctx);
// The app holds the position, and is told where a person moves it.SeekBar::controlled(at, 250.0, move |to| seek_to(to));| Builder | |
|---|---|
new(Signal<f32>, duration) | Bound to the position, in seconds, of something duration seconds long (0 where it is not known). A drag, a press on the track and the keys set the signal |
controlled(position, duration, on_change) | The app holds the position; the bar shows it and tells on_change where a person moves it, and shows what the app answers |
buffered(seconds) | How far it is loaded: drawn between what is played and the rest |
chapters(&[f64]) | Where the chapters start, in seconds: the track is cut there, 2 apart. The first starts at 0, given or not |
step(seconds) | What an arrow key moves it: 5 seconds unless told. A drag is not snapped to it |
on_media(bool) | It stands over a picture: white, the same in a light and a dark theme |
size(SeekBarSize) | Md (16 high) or Lg, a phone’s: 28 high with a thumb of 28, 16 over a picture |
preview(Fn(f64) -> Element) | A picture of the moment under the pointer, given its time: shown in a frame of 128 by 72 over the time. Shown by a mounted bar |
on_change(Fn(f64)) | The position, in seconds, each time a person moves it. Bound, it is called after the signal is set. Each call adds |
on_change_end(Fn(f64)) | Where a drag is let go, a press is over or a key’s step is made, where it moved. Each call adds |
on_hover(Fn(Option<f64>)) | The time under the pointer as it moves over a mounted bar, and None when it leaves. Each call adds |
empty(bool) | Nothing is loaded: the track alone, with nothing played or loaded and no thumb, and it takes no input (no stop of Tab). A player draws it while it loads and after an error. It is not dimmed |
live(bool) | A live stream with nothing to go back in: the bar full, the thumb at its end, and a press, a drag and the keys tell nothing (no stop of Tab). The whole may be of no length |
label(&str) | What it is called, to what reads the tree: “Seek” unless told |
mount(ctx) | Puts it where it goes keeping the time under the pointer and the width it is laid out at: it shows the chip with the time, and the preview over it. .child(bar) is the same component, declared: what renders the tree mounts it |
build(theme) | A still picture for a test or a screenshot: with no chip, and it reads nothing of a pointer that does not press it |
disabled(bool), state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. id is the id of what is dragged and focused. A mounted bar forced Hovered shows its position in the chip |
- It is the engine’s slider over a track the bar draws itself: the engine’s slider takes the drag, the press on the track and the focus, and paints the thumb; the track, what is played, what is loaded and the chapters’ gaps are the bar’s. The track’s ends are half the thumb wide, so what is played ends under the thumb’s middle.
- The keys: Right and Up a step later, Left and Down a step earlier, Page Up and Page Down a tenth of the whole in whole steps, Home and End to the ends. A disabled bar is not a stop of Tab and takes nothing.
- Parts:
SeekBarPart::Root(the bar),Track,Chapter(the room between two is its padding at the side they share),Played,Buffered,Rest,Control(the engine’s slider),Thumb,Hover(what stands over the pointer),Preview(the frame),Tip(the chip with the time). States:SeekBarState::Disabled,OnMedia,Chapters,Buffered,Preview,Empty,Live. Sizes:SeekBarSize::Md,Lg. - In the design (Media/Seek Bar) it is 16 high with a track of 4 whose ends are round by 2: played in
Primary, loaded inMutedForegroundat half its opacity, the rest inSecondary, and the Slider’s thumb, 16, inBackgroundwith an edge of 1.5 inPrimary. The ring of the focus is the thumb’s. Disabled it is at half its opacity and draws nothing loaded. Over a picture (Media/Seek Bar/On Media) played and a solid thumb of 12 are#FFFFFF, loaded#FFFFFF59, the rest#FFFFFF33, and the ring of the focus is white: the picture is not themed. The time under the pointer (Media/Seek Preview) is in a tooltip’s chip, the mono type at 12 onPrimary, 4 above the bar and centred on the pointer; the preview’s frame is 6 above the chip, with a radius md and an edge of 2 in white, and the two stand 6 above the bar. - To what reads the tree it is a
slidercalled by its label, witha11y_valuereading “1:24 of 4:10”. - A renderer that draws another bar starts from
view.dressed(view.control()), the behavior with the thumb’s style;view.track()is the default track andview.hover_layer()what stands over the pointer.
Media Time
Section titled “Media Time”The time a player reads out: how far it is, and how long the whole is.
use lurq::ui::{MediaTime, MediaTimeSize};
MediaTime::new(position, Some(duration));
// Over a video, turning between elapsed and remaining on a press.MediaTime::new(position, Some(duration)) .on_media(true) .remaining(left.get()) .on_click(move |_| left.set(!left.get()));
// A compact player's; and a stream that is live.MediaTime::new(position, Some(duration)).size(MediaTimeSize::Sm);MediaTime::new(0.0, None).live(true);| Builder | |
|---|---|
new(position, Option<f64>) | The time at position seconds of a whole of that many seconds; None while the length is not known: it reads -:-- / -:-- |
remaining(bool) | It reads what is left, with a minus before it, alone |
on_media(bool) | It stands over a picture: white, the ”/” and the whole #FFFFFF99, the same in a light and a dark theme |
live(bool), live_text(&str) | A live stream: a badge, solid in Destructive, reads “LIVE” (or the text given) in place of the time |
size(MediaTimeSize) | Sm (11, a compact player’s and an audio player’s), Md (12), Lg (13, a phone’s player held across) |
on_click(handler) | A press: a player turns the reading between elapsed and remaining. Given it, the time is a button, a stop of Tab with the ring of the focus, which Enter and Space press. Each call adds |
label(&str) | What it is called, to what reads the tree: what it reads unless told (“1:24 of 4:10”, “2:46 left”) |
state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. force shows only on a time that is pressed |
- From an hour up both readings have hours (
1:02:45 / 2:10:00).media_time_text(seconds, hours)is a reading alone as a string,media_rate_text(rate)a speed as a menu names it, andMEDIA_RATESthe speeds a player offers. - Parts:
MediaTimePart::Root(the row, or the button),Elapsed,Divider,Total,Live(what the recipe lays over the badge’s root). States:MediaTimeState::OnMedia,Remaining,Unknown,Live,Pressable. Sizes:MediaTimeSize::Sm,Md,Lg. - In the design (Media/Time) it is the mono type at 12, 4 between the readings, the elapsed time in
Foregroundand the ”/” and the whole inMutedForeground; not loaded the elapsed-:--is muted too. The mono type keeps it from jumping as it counts.
Waveform
Section titled “Waveform”The loudness of a recording as a row of bars, the played part of it marked: a voice message’s seek bar.
use lurq::ui::Waveform;
// Shown and not operated, a third of it played.Waveform::at(0.33, &peaks);
// Bound to how far it is played, from 0 to 1, which a press, a drag and the keys set.Waveform::new(progress.clone(), &peaks).on_change_end(move |to| player.seek(to * length));
// The app holds it, and is told where a person presses or drags to.Waveform::controlled(at, &peaks, move |to| seek_to(to));
// Not heard yet: every bar in the color of what is not played.Waveform::at(0.0, &peaks).unheard(true);| Builder | |
|---|---|
at(progress, &[f32]) | Shown and not operated: progress of it played, from 0 to 1; no stop of Tab, and a press does nothing |
new(Signal<f32>, &[f32]) | Bound to how far it is played, from 0 to 1, which a press, a drag and the keys set |
controlled(progress, &[f32], on_change) | The app holds how far it is; the waveform shows it and tells on_change where a person presses or drags to |
unheard(bool) | Nothing of it was heard yet: every bar in the color of what is not played |
step(f64) | What an arrow key moves it, from 0 to 1: a twentieth unless told |
on_change(Fn(f64)) | Where a person moves it, from 0 to 1, as a press or a drag moves it. Bound, it is called after the signal is set. Each call adds |
on_change_end(Fn(f64)) | Where it ends: the drag let go, the press or a key’s step made, where it moved. Each call adds |
label(&str) | What it is called, to what reads the tree: “Seek” unless told |
disabled(bool), state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. id is the id of what is pressed where it is operated; force shows only on one that is operated |
peaksare the heights of its bars, each from 0 to 1, one for each bar: about 36 for a voice message. How many are played isprogressof them, rounded.- Operated it is the engine’s slider over the bars, as large as they are and drawing nothing but the ring of the focus: the arrow keys move it a step, Page Up and Page Down a tenth, Home and End to the ends. A disabled one is not a stop of Tab and takes nothing.
- Parts:
WaveformPart::Root,Bars(the row),Bar(one not played),Played,Control(the engine’s slider). States:WaveformState::Disabled,Unheard,Operated. - In the design (Media/Waveform) the bars are 3 wide and 2 apart, fully round, at most 24 high and no lower than they are wide; the played ones in
Primary, the rest inInput. Operated, the ring of the focus is around the bars at a radius sm; disabled, it is at half its opacity. - To what reads the tree an operated waveform is a
slidercalled by its label, witha11y_valuethe percent played.
Play Button
Section titled “Play Button”The round control that starts and pauses what a player plays, and plays it again once it has ended.
use lurq::ui::{PlayButton, PlayButtonSize, PlayButtonVariant};
// playing: Signal<bool>. A press tells what it is to be.PlayButton::new() .playing(playing.get()) .on_change(move |next| playing.set(next));
// In the middle of a paused video, over the picture.PlayButton::new() .variant(PlayButtonVariant::Overlay) .size(PlayButtonSize::Xl) .replay(ended.get()) .on_change(move |next| play(next));| Builder | |
|---|---|
playing(bool) | Whether what it plays is playing: the glyph is pause. The button does not keep it: the app says so |
on_change(handler) | Called on a press with what it is to be: playing if it was paused or had ended. Not while it is loading or disabled. A second handler is called after the first |
replay(bool) | What it played has ended: the glyph is rotate-left, and a press tells true |
loading(bool) | What it would play is still being fetched: the spinner glyph turns in the glyph’s place, the disc is at 75%, and a press does nothing |
size(PlayButtonSize) | Sm 32 with a glyph of 14, Md 40 with 16 (the default), Lg 48 with 20, Xl 64 with 28 |
variant(PlayButtonVariant) | Primary on a surface of the theme; Overlay over a picture |
play_label(&str), pause_label(&str), replay_label(&str) | What it is called while a press would play, pause or play again: “Play”, “Pause”, “Replay” |
disabled(bool), state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. id is the id of the disc |
- A click, Enter and Space press it; Tab reaches it, and the ring of the focus is drawn from the keyboard.
- Parts:
PlayButtonPart::Root(the disc, what is pressed),Icon. States:PlayButtonState::Playing,Replay,Loading,Disabled. VariantsPlayButtonVariant::Primary,Overlay; sizesPlayButtonSize::Sm,Md,Lg,Xl. - In the design the disc is round, in
Primarywith the glyph inPrimaryForeground,PrimaryHoverunder the pointer; held down it isPrimaryunder the pressed veil, as the primary button is. Loading it is at 75%, disabled at half. - Over a picture the disc is
#00000099(black at 60%) with a white glyph and a white ring of the focus, the same in a light and a dark theme: the picture is not themed, and a themed control would lose its contrast on it. The board draws no overlay under the pointer: it is#000000B3, the end of the board’s bar gradient. The board uses the overlay atXlin a player andLgin a compact one. - To what reads the tree it is a
buttoncalled by the label of what a press would do; loading it saysa11y_busy. - A renderer that draws another play button starts from
view.root(), the behavior with the disc’s style, andview.icon(), the glyph of the state it is in (view.icon_name()).
Volume
Section titled “Volume”A button that mutes and a slider of how loud, in a player’s bar. Muting keeps the volume, so that the sound comes back as loud as it was.
use lurq::ui::{MediaVolume, MediaVolumeSize};
// volume: Signal<f32> from 0 to 1, muted: Signal<bool>.MediaVolume::new(volume.clone()).muted(muted.clone());
// The app holds both, and is told what a person makes them.MediaVolume::controlled(player.volume(), move |volume| player.set_volume(volume)) .muted_controlled(player.muted(), move |muted| player.set_muted(muted));
// In a video's bar, over the picture; in a narrow one, the button alone until the pointer or the focus is in it.MediaVolume::new(volume.clone()).muted(muted.clone()).on_media(true).size(MediaVolumeSize::Lg).length(64.0);MediaVolume::new(volume.clone()).muted(muted.clone()).on_media(true).collapsed(true).mount(ctx);| Builder | |
|---|---|
new(Signal<f32>) | Bound to the app’s volume, from 0 to 1, which a drag, a press on the slider and the keys set |
controlled(volume, on_change) | The app holds the volume and is told what a person makes it |
muted(Signal<bool>), muted_controlled(bool, handler) | Muted while true, which a press of the button turns. Muted, the slider stands at nothing and the volume is kept |
on_change(handler) | Called with the volume each time a person moves it. Bound, after the signal is set |
on_change_end(handler) | Called with the volume when a drag is let go or a key’s step is made |
on_muted_change(handler) | Called with whether it is to be muted: on a press of the button, and with false when the slider is moved up from nothing while muted |
collapsed(bool) | The button alone, the slider beside it while the pointer is over the control, the focus is in it or it is being dragged. What it keeps for that is mount(ctx)’s; a still picture (build(theme)) is the button alone |
on_media(bool) | Over a picture: white, the same in a light and a dark theme |
size(MediaVolumeSize) | Md: a button of 32 with a glyph of 16 (the default); Lg: 36 with 20, as a video’s bar has it |
length(f32) | How long the slider is, in place of the recipe’s 72 |
label(&str) | What the slider is called: “Volume” |
mute_label(&str), unmute_label(&str) | What the button is called while a press would mute or bring the sound back: “Mute”, “Unmute” |
mount(ctx) | Puts it in the tree of ctx’s component, keeping whether the pointer is over it, the focus is in it and its slider is being dragged. .child(volume) is the same component, declared: what renders the tree mounts it |
disabled(bool), state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. id and force are the button’s |
- The glyph is
volumefrom a half up,volume-lowunder it, andvolume-offwhile muted or at nothing. Muted, the slider stands at nothing and the app’s volume is not touched; moving the slider up from there sets the volume and tellson_muted_change(false)once in the gesture. - Tab reaches the button, then the slider: Space and Enter press the button, the arrows move the slider a twentieth, Page Up and Page Down a tenth, Home and End to nothing and to the whole. A disabled control is passed by.
- Parts:
MediaVolumePart::Root(the button and the slider, side by side),ButtonandIcon(laid over a button’sRootandIcon),Slider,Track,Fill,Thumb(laid over a slider’s parts). States:MediaVolumeState::Muted,Collapsed,OnMedia,Disabled. SizesMediaVolumeSize::Md,Lg. - In the design the button is a ghost one of 32 with a glyph of 16 and the slider is 72 long, 4 apart. Over a picture the glyph is white, the button
#FFFFFF1Funder the pointer and#FFFFFF33held down with a white ring of the focus; the slider’s range and thumb are white, the thumb 12 with no edge, and its rail is#FFFFFF33. - To what reads the tree the button is a
buttoncalled by what a press would do, and the slider aslidercalled bylabel. - A renderer that draws another volume control starts from
view.button()andview.slider(), the button and the slider dressed by the recipe with their behavior;view.revealedsays whether the slider is shown.
Speed Menu
Section titled “Speed Menu”The menu a player’s speed is chosen from: the speeds under the heading “Playback speed”, the one in use checked at the end of its row.
use lurq::{ components::Placement, ui::{MediaSpeedMenu, media_rate_text},};
// open: Signal<bool>, set by a press of the speed button; speed_button: ElementRef; speed: Signal<f32>.MediaSpeedMenu::new(open.clone(), speed_button.clone(), speed.get()) .on_change(move |rate| speed.set(rate as f32));
// From a bar at the bottom of a picture, opening up from the button's end, with the app's own speeds.MediaSpeedMenu::new(open.clone(), speed_button.clone(), speed.get()) .rates(&[0.25, 0.5, 1.0, 1.5, 2.0, 3.0]) .placement(Placement::TopEnd);| Builder | |
|---|---|
new(open, anchor, rate) | Open while the signal is true, hung from the anchor, with rate checked |
on_change(handler) | Called with the speed chosen, after the menu has closed, where it is another than the one in use. A second handler is called after the first |
on_dismiss(handler), on_open_change(handler) | As a menu has them: a person closed it other than by choosing; a person closed it, a choice too, after on_dismiss |
rates(&[f32]) | The speeds offered, in place of MEDIA_RATES (0.5×, 0.75×, Normal, 1.25×, 1.5×, 2×). Each is named by media_rate_text |
heading_text(&str) | The words over the speeds: “Playback speed” |
label(&str) | The menu’s name to tooling: its heading unless told |
placement(Placement), offset(..), collision(..), inline(bool) | As a menu has them |
state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. id is the panel’s; force draws the speed in use |
- It is a menu: choosing a speed, Escape, a press outside and Tab close it, Up and Down move between the speeds, Enter chooses. Choosing the speed in use closes it and tells
on_changenothing. - Parts:
MediaSpeedMenuPart::PanelandLabel(laid over a menu’sPanelandLabel),Item,ItemLabel,Check(laid over a menu item’sRoot,LabelandCheck). State:MediaSpeedMenuState::Inline. - In the design it is the menu’s panel 168 wide (where a menu is at least 230), with the group label and a menu item for each speed; the check is at the end of the row of the speed in use. Over a picture it stays themed: it is the system’s own surface, and opaque.
- A renderer that draws another speed menu starts from
view.menu(), the menu with its speeds, orview.item(rate)for one speed.
Playing a video
Section titled “Playing a video”VideoPlayer::source(&Source) (feature media) makes a mounted player play what the source holds: a file, bytes, a resource of the app, an address.
VideoPlayer::new() .source(&Source::file("clips/lake.mp4")) .width(640.0) .max_width(Length::Fill) .mount(ctx)An address is read as it plays, and the source’s headers are on each of its requests: a host that serves only its own pages is given its Referer, one that serves only who signed in its Authorization.
VideoPlayer::new() .source(&Source::url("https://videos.example.com/lake.mp4").header("Referer", "https://example.com/")) .mount(ctx)On Windows the app’s loader reads every address as it plays (the feature http; a build without it has the system read it, with no header): seeking asks the server for the part it goes to, the player waits where it has nothing left to show while the part it needs is still on the network (not while it reads ahead), and a server that refuses on the way is the error it shows (MediaError::Server(403)). The loader’s rule gives headers to every address of a host (app.loader().headers(..)). On macOS and iOS the system’s player is given them. A browser plays no video yet, and its <audio> cannot send them (see Loading).
The player opens the source with the app’s loader, decodes it with the system’s decoder and draws its frames as its picture. Where it is, how long it is, and whether it plays, waits, ended or failed are the media’s, in place of what the app would say. A press on a control tells the app’s handlers and does what it says to the media: play, pause, the seek bar, the speed, the keys. An app that holds playing or rate (a signal, or a value it sets) moves the media by changing them. With no source the player is drawn from the values it is given, as before.
What happens to the media is told to the app, as a browser’s <video> tells it:
VideoPlayer::new() .source(&Source::file("clips/lake.mp4")) .on_load(|info| println!("{:?} long, {:?}, sound: {}", info.duration, info.size, info.sound)) .on_error(|why| tracing::warn!("{why:?}: {}", why.detail().unwrap_or_default())) .on_started(move || poster.set(false)) .on_ended(move || next.set(true)) .on_playing_change(move |plays| playing.set(plays)) .on_waiting_change(move |waits| buffering.set(waits)) .mount(ctx)- Each is told on the UI thread, once each time it happens, in the order the media lives them: it opened, it began or stopped waiting, it began or stopped playing, it started, it ended, it failed. A handler may set signals and move the media; what it sets is drawn in the same frame.
on_startedis told when the video really plays: it was told to play, it does not wait for what it plays, and the first frame since is on the screen (for a sound, its sound is given to the output).on_loadcomes before it, with nothing moving yet, and so doeson_playing_change(true), which a press tells at once: between them andon_startedthe player shows the frame it stood on, or nothing. An app that covers the player with a poster of its own takes it away here, and measures from a swipe to here how long a video took to move. It is told again after a pause, after it waited and after its end; not for a round of aloopedone, which did not stop, nor for a seek while it plays.on_endedis told again only after it played again.on_erroris told a kind (core::MediaError), whose words are the locale’s (MediaWords::error), once until the person tries again, which opens the source anew. Waiting is reading what is not there yet once it opened (an address on Apple’s systems); opening is not waiting.on_playing_changehears a press, as without a source, and the media stopping or starting by itself: at its end, when it fails, a sound that starts over. What a press told or the app set is not told again when the media does it. A signal bound toplayingfollows the media at its end, and that is not the app pausing it.- A player without a source tells none of these: whether it waits, ended or failed is what the app gives it.
- How far it is loaded is the media’s too:
VideoPlayback::bufferedin a layer of the app’s (child_with), and the lighter part of the player’s own seek bar. It is how far the video is fetched from where it plays, andNonewhere that is not known: a line of the app’s draws nothing as loaded then (SeekBar::buffered(playback.buffered.unwrap_or(0.0))). A looped video near its end is fetched to its end; gone on from its start, it is fetched as far as what is held from there, which for a long one may be its first megabyte alone.
A clip that plays round and round, as in a feed, is looped:
VideoPlayer::new() .source(&Source::url("https://videos.example.com/clip.mp4")) .looped(true) .on_ended(move || rounds.update(|count| *count += 1)) .mount(ctx)At its end the media goes to its start in what it has open: nothing is opened again, an address read through the app’s loader is asked for nothing it holds (its first megabyte is always held, and the sixteen blocks read last), and it does not stop. on_ended is told each time round; playing stays true, and on_playing_change is told nothing. Setting playing again in on_ended did this with a stop at the seam. Media::set_looped(true) is the same for an app’s own player, and AudioPlayer::looped(true) for a sound.
Your own controls over a video
Section titled “Your own controls over a video”A player with controls(false) is its picture and the app’s layer. With a source, where it is and how long it is are the media’s, and no signal of the app’s follows them: a layer that shows the time is built from the player itself, with child_with. It is given a VideoPlayback each time the player is rendered, which is as often as the player’s own bar would be drawn again, and its seek, set_playing and set_muted do what the player’s own controls do: the media is moved, and the app’s handlers are told.
use lurq::ui::{MediaTime, PlayButton, PlayButtonVariant, SeekBar, VideoPlayer};
VideoPlayer::new() .source(&Source::url("https://videos.example.com/clip.mp4")) .poster(still) .looped(true) .controls(false) .child_with(move |playback| { let (to, play) = (playback.clone(), playback.clone()); Stack::new() .child( PlayButton::new() .variant(PlayButtonVariant::Overlay) .playing(playback.playing) .on_change(move |plays| play.set_playing(plays)), ) .child(MediaTime::new(playback.position, playback.duration).on_media(true)) .child( SeekBar::controlled(playback.position, playback.duration.unwrap_or(0.0), move |at| to.seek(at)) .on_media(true), ) }) .mount(ctx)- The layer is built in the player’s own render: it reads no signal for the time, and nothing but the player is rendered again as the video plays. What it captures is moved into it (elements built once outside are cloned in it).
playback.openingis true until the video’s first frame is there, andplayback.waitingwhile it reads what is not there yet: a spinner of the app’s own shows on either.- A poster stays over the box until the first frame is there, also where the player plays at once, so a feed shows the still of its next video and not a black box. Without a poster the box shows its
background, black unless told.
A video opened ahead
Section titled “A video opened ahead”A feed wants the video after the one shown to start at once. A player that is given its source and not told to play is that: it opens the source, shows its first frame (under its poster, where it has one) and stays paused at its start, and it plays at once when playing is set.
-
Its poster or its first frame. A poster is the picture of a player until it plays, so a player opened ahead shows its poster while a finger slides it in, and the video when it plays: two pictures, since a poster is seldom the video’s first frame (another moment, often another crop).
poster_until_frame(true)makes the poster stand only until the first frame is decoded: the page that slides in shows that frame, and playing goes on from the very picture that was seen. The poster is there while the frame is still to come, so the box is never the black a media opens with. It holds wherever the first frame is decoded while paused: Media Foundation on Windows andAVPlayeron Apple’s systems; a browser build decodes no video yet, and keeps the poster. -
From an address it then reads what opening asks for and nothing ahead of it. On Windows that is one request, for the first 256 KiB, which is what Media Foundation reads of a file at a time, and the 16 KiB about an index kept at the file’s end where it has one there. A neighbour opened ahead does not take the connection from the video that plays.
-
Told to play, it reads ahead of what plays from then on (the two blocks after the one read, see Loading), and what follows its start is asked for at once.
-
Media::openwith noplayis the same for an app’s own player;Media::has_frame()says when its first frame is there, andMedia::is_open()when it opened.
An app that draws its own player asks for a media itself:
let media = Media::open(app.loader(), &Source::file("clips/lake.mp4"));media.play();let picture = media.frame().map(Video::new); // drawn again by itself as frames comelet state = media.state(); // duration, position, buffered, size, playing, waiting, ended, error, ratemedia.seek(42.0);media.set_rate(1.5);media.on_change(|| { /* it changed: called on the media's own thread, with nothing said */ });// Its events, on the UI thread, once each time: as a player's.media.on_load(|info| println!("{:?} by {:?}", info.duration, info.size));media.on_error(|why| tracing::warn!("{why}"));media.on_started(|| println!("it plays"));media.on_ended(|| println!("the end"));media.on_playing_change(|plays| println!("playing: {plays}"));media.on_waiting_change(|waits| println!("waiting: {waits}"));See Media events for how they reach the UI thread.
Playing a sound
Section titled “Playing a sound”AudioPlayer::source(&Source) (feature media) makes a player play what the source holds: a file, bytes, a resource of the app, an address.
AudioPlayer::new(position, 0.0) .source(&Source::url("https://example.com/night-drive.mp3")) .title("Night Drive") .volume(volume)The player opens the source as a sound and plays it through the system’s output. Where it is, how long it is, and whether it plays, loads or failed are the sound’s, in place of what the app would say: the length given to new is drawn only until it opened. A press on a control tells the app’s handlers and does what it says to the sound: play, pause, the seek bar, the volume, the mute, the speed. An app that holds playing, volume, muted or rate moves the sound by changing them. With AudioRepeat::One the track starts over at its end. “Try again” loads the source anew.
Its events are a video player’s (on_load, on_error, on_ended, on_playing_change, on_waiting_change): an app that plays a queue goes on to the next track in on_ended. A ui::AudioQueue is the list the app shows and plays nothing itself; the player that plays its current item tells each end.
A sound at an address is loaded whole through the app’s loader (its headers, its timeout, what it allows; the feature http), and kept: played again, by this player or another, it starts at once and asks the network for nothing. While it loads the player is drawn loading. One larger than the loader reads whole (max_bytes) is read as it plays, with its headers as a video’s are, and not kept. What is kept is what the server sent, up to 64 MiB of sounds; over that, what was played longest ago is let go.
sound_cache().budget(256 * 1024 * 1024); // keep moresound_cache().forget(&source); // this one has changed: load it againsound_cache().clear();That is kept in memory, for the run of the app. An app that gives a folder has what it loads from addresses kept there as files, for its next run too:
// The folder is the app's own cache folder: lurq picks none.let app = App::new().enable_media_disk_cache(cache_folder);app.loader().media_disk_cache().budget(2 * 1024 * 1024 * 1024); // 512 MiB unless toldA sound then plays from its file and is not kept in memory as well, and a player of a sound an earlier run kept opens it as it is drawn. sound_cache() goes on answering whether a sound is kept and how much is, and forget and clear delete the files too; its budget is of the memory alone. Over the folder’s budget the file used longest ago is deleted. What is kept is not asked of the server again, however old it is: an app that knows a sound changed forgets it. See Loading.
An app that draws its own player asks for the sound itself:
let song = Media::sound(app.loader(), &Source::file("songs/night-drive.mp3"));song.set_volume(0.8);song.play();song.set_muted(true);let state = song.state(); // duration, position, buffered, sound, volume, muted, playing, waiting, ended, error, rateA video has its sound too: Media::open and VideoPlayer::source play it, and the picture goes by what is heard.
Picture
Section titled “Picture”An image in its box: it covers the box unless told otherwise, shows a skeleton while it loads and its name when it cannot be shown, and carries a badge, a bar and a layer of the app’s over it.
use lurq::ui::{Picture, PictureFit, PicturePlaceholder};
// Pixels the app has, a file, bytes, a resource of the app, an address.Picture::from_file("photos/lake.jpg") .label("The lake at dusk") .size_px(640.0, 360.0) .lightbox(true);
// As wide as its room, 3 by 2 before its pixels are there, with a small version blurred while they come.Picture::from_url("https://example.com/lake.jpg") .label("The lake at dusk") .aspect_ratio(3.0 / 2.0) .placeholder(PicturePlaceholder::blur("photos/lake-small.jpg")) .on_error(|why| tracing::warn!("{why:?}: {}", why.detail().unwrap_or_default()));
// A figure: the picture with a caption under it.Picture::from_resource("images/lake.jpg") .width(320.0) .caption("Figure 1. The lake at dusk.");| Builder | |
|---|---|
new(ImageData), from_file(path), from_bytes(bytes), from_resource(path), from_url(url), from_source(source), empty() | Pixels the app has; a file or bytes, decoded off the UI thread; a resource of the app or an address, read by the app’s Loader; any resources::Source; or no source: a box that says it has no picture. ImageData converts into a picture. An address outside a browser needs the feature http, decoding the feature image: without it the box says the picture did not load, and why |
cache_key(u64), downscale_to(width, height) | The key the decoded pixels are kept under, for bytes the app tells apart itself; and the most pixels that are kept of a large picture |
label(&str), decorative(bool) | What the picture is called: what it shows of itself where there are no pixels, and its name to tooling. A decorative one says nothing to tooling |
width(Length), height(Length), size_px(width, height), aspect_ratio(f32) | As a browser’s img: with neither side it is as large as its pixels, with one the other follows their ratio, with both it is a box. A ratio gives the side that is not said, and with neither makes the box as wide as its room; it holds the box of a picture whose pixels are not there yet. The width is the most the box takes: in a narrower room it is as wide as the room, and a box of pixels keeps its shape |
fit(PictureFit), anchor(StackAlignment) | Cover (the default), Contain, Fill, None (its own size); and which side is kept where the pixels are cut or do not fill the box |
shape(PictureShape), bare(bool) | Rounded or Circle; bare is the pixels alone, with no fill, no corners and no line |
size(PictureSize) | The form: Lg from 240 wide, Md under it, Sm at 96 and under, Xs at 40 and under. Not said, it follows the width the box gets: the width in pixels it was told, or less where its room is narrower, or the width of its room |
placeholder(PicturePlaceholder) | What the box shows while the pixels are on their way: Skeleton (the sheen), blur(source) or blur_pixels(data) (a small version of the picture, blurred), None (the box alone) |
loading(bool), progress(Option<f64>), progress_text(Fn(PictureLoad) -> String) | The box as while its pixels are on their way, for a picture the app is still fetching; how far the load has come, of 1, which draws a rail in place of the sheen; and the words under the rail. A picture that loads from an address shows its own progress where the server says how long it is |
on_load(Fn()), on_error(Fn(&PictureError)), on_retry(Fn()) | Told once the pixels are there; once the picture did not come, with why; and on a press of “Try again”, before the picture asks again. Why is a kind: NotFound, Denied, TimedOut, TooLarge, Server(status), Network, NotAPicture (bytes that are no picture the decoder reads), Unavailable (a build without image, an address without http) and Other; the locale says it (MediaWords::picture_error), and what the system or the decoder said is kept for a log (PictureError::detail) |
error_description(&str), retry_label(&str), download_label(&str), more_label(&str), open_label(&str) | Its words: “The picture didn’t load.”, “Try again”, “Download”, “More”, “Open” |
title(&str), description(&str), badge(element) | What the bar along the bottom says, and what stands at the top, at the start. The bar shows under the pointer and with the focus |
on_download(Fn()), menu_item(MenuItem), menu_items(..), action(element), actions(..) | The bar’s Download button, the menu behind More, and buttons of the app’s |
bar(bool), force_bar_shown(Option<bool>) | Whether the bar is drawn, and whether it shows whatever the pointer does |
child(element), children(..) | The app’s own layer over the whole picture |
caption(&str) | A caption under the picture, which makes it a figure |
on_click(handler) | A press of the picture as a whole |
selectable(bool), selected(bool), on_change(Fn(bool)) | A picture that can be chosen, whether it is, and what a press would make it. The picture does not keep it |
lightbox(bool), open(Signal<bool>), on_open_change(Fn(bool)) | A press, and the last button of a large picture’s bar, open the picture alone in a lightbox over the window, with its title and description; whether it is open, to read and to set; and what tells of it. Without a signal the picture keeps it. A picture that is chosen by a press is opened by the button |
variant(PictureVariant) | Desktop, or Phone (the board’s Mobile/Picture, T9drb): a large picture runs edge to edge with no corners and no line, its badge 16 in, its bar always there with no buttons and a title of 15, and a long press brings its actions, Download and the menu’s items, in an action sheet. A picture is the phone’s under a finger, Pointer::Coarse (the touch form), whatever the window’s width and the density, unless told |
disabled(bool), state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. id is the id of the box |
- A picture is a component of its own wherever it is put:
Row::new().child(Picture::from_url(..)). It is mounted by the component whose render returns it, keeps its load, its menu and its lightbox there, and is told apart from its like by its place or itskey. In a tree no component renders (Tree::set_root(element)) it shows nothing.mount(ctx)mounts it at once, for a place that needs the element. - A picture made of the same plain things as the last time is not rendered again with what holds it: a list of five hundred costs what its changed pictures cost. A handler, a child, a badge or a menu makes it render with its parent.
- While a box that does not wait for its pixels loads, what stands in for them goes out over them as they come; a box the pixels size drops it at once.
- A press, Enter and Space press a picture that takes a press; Tab reaches it, and the ring of the focus is drawn from the keyboard. The buttons of the bar are pressed on their own, and the picture is not.
- Parts:
PicturePart::Figure,Root,Image,Edge,StandIn,Sheen,Veil,Overlay,Center,Mark,Label,ErrorIcon,ErrorLabel,ErrorDescription,Retry,Progress,Track,Fill,ProgressLabel,ProgressLine,Count,Top,Select,SelectIcon,Controls,Text,Title,Description,Actions,Control,ControlIcon,MoreMenu,Caption. States:PictureState::Bare,Circle,Pressable,Selectable,Selected,Disabled,Shown(the bar is held shown),On(a button of the bar whose menu is open). SizesPictureSize::Xs,Sm,Md,Lg. - In the design the box is
Mutedwith a line ofBorderinside it, round byRadiusSize::Lg(Mdfor a small one); the bar is white on a gradient to black at 70% in both themes, since the picture is not themed. A chosen picture has a disc ofPrimarywith a check at its top end and a line ofPrimaryabout it. - To what reads the tree it is an
imgcalled by its label, abuttonwhere it is pressed, acheckboxwhere it is chosen, and afigureabout the two where it has a caption. - A renderer that draws another picture has
view.frame()(the box with everything in it), and the pieces it is made of:view.image(),view.empty(),view.overlay(),view.top(),view.controls(),view.edge().
Lightbox
Section titled “Lightbox”Pictures one at a time, whole, over the window: to look at closely, to bring closer, to turn through.
use lurq::ui::{Lightbox, Picture};
// open: Signal<bool>. Open while it says so; Escape, a press beside the picture and Close set it to false.Lightbox::new(open.clone(), photos.iter().map(|photo| Picture::from_file(&photo.path).title(&photo.name))) .index(shown.clone()) .wrap(true) .on_download(move |which| save(which));
// One picture needs none of this: Picture::lightbox(true). A grid of them: Gallery.| Builder | |
|---|---|
new(open, pictures), picture(Picture), pictures(..) | Open while the signal says so, with the pictures it shows. Each is shown whole (Contain), with its title and description over its lower edge; what else a picture has over it (a bar, a badge, a mark) is not shown |
index(Signal<usize>), index_controlled(index, on_change), on_index_change(Fn(usize)) | Which picture is shown, counted from 0. Without either the lightbox keeps it and starts at the first |
zoom(Signal<f32>), on_zoom_change(Fn(f64)), zoom_max(f32) | How close the picture is, 1 where it fits; and the closest it is brought, 4 unless set. Turning to another picture fits it again |
variant(LightboxVariant), on_share(Fn(usize)), menu_item(MenuItem), menu_items(..), share_label, more_label | Desktop, or Phone: the phone’s viewer, which a lightbox is under a finger, Pointer::Coarse (the touch form), over a window of any width and in a page, whatever the density, unless told. In a narrow window of a desktop it is the desktop’s, laid out in the room it has. Open, it keeps the form it opened in until it closes (in a page, the one it was first shown in); the app setting the pointer changes it at once. On a phone, the Share button with the picture shown, and the menu behind More, which holds Download first where it is given |
preload(usize) | How many pictures each way of the one shown are brought on once its own pixels came, read by the app’s loader and decoded, so that an arrow shows the next at once: 1 unless told, 0 for none, round the ends where it wraps |
wrap(bool) | Whether the first picture comes after the last |
filmstrip(bool), counter(bool), counter_text(Fn(usize, usize) -> String) | The strip of small pictures and the counter: both show with more than one picture unless told. The counter says “3 / 12” |
on_download(Fn(usize)) | Shows the Download button, and is called with the picture shown |
action(element), actions(..) | Buttons of the app’s in the top row, before Download |
inline(bool), width(Length), height(Length) | Stands in the page where it is declared, open or not, in place of over the window: for a gallery, a screenshot, a test, a viewer that is part of a page. Its size there; the width is the most it takes |
on_dismiss(Fn()), dismiss_on_escape(bool), dismiss_on_veil(bool), close_button(bool) | Told when a person closes it; and whether Escape, a press beside the picture and a Close button do |
label, close_label, previous_label, next_label, zoom_in_label, zoom_out_label, fit_label, download_label | Its words to tooling: “Pictures”, “Close”, “Previous picture”, “Next picture”, “Zoom in”, “Zoom out”, “Fit to the window”, “Download” |
state(name, on), style(part, ..), rules(&recipe), id, key | As a button has them. id is the id of the panel; its parts are <id>-close, -next, -previous, -zoom-in, -zoom-out, -level, -download, -stage |
- It is a component wherever it is put, as a picture is: it keeps which picture is shown, how close, and where the view is.
- The wheel brings the picture closer about the pointer, turned away from the hand, and further toward it, and a drag moves it; two fingers on a touch screen pinch and pan. On a touchpad two fingers move the picture and their pinch brings it closer (on Windows, as Ctrl and the wheel do); a Mac trackpad’s smart zoom is a double tap. A double click goes to twice the size it fits and back.
- Keys, while the focus is in it: the left and right arrows turn to the picture before and after, and move a
picture that is closer than it fits, as the up and down arrows do;
+and-bring it closer and further,0fits it; Escape closes. Over the window it takes the focus. - The level says how close the picture is as a share of the size it fits at (100% fitted), and a press of it fits the picture again. In a panel too narrow for the whole top row the level is not there.
- The strip shows as many small pictures as it has room for, about the one shown.
- Parts:
LightboxPart::Veil(what covers the window),Root(the panel),Top,Counter,Total,Control,ControlIcon,Level,Stage,Step,StepIcon,Side,Caption,Title,Description,Filmstrip,Thumb. States:LightboxState::Inline,Current(the small picture of the one shown). - In the design it is white on near black (
#09090BF2) in both themes, since a picture is not themed: a top row of 52 with the counter in the mono face and buttons of 36, round buttons of 36 on black at 40% over the sides of the stage, a caption on a gradient to black at 70%, and a strip of 52 with pictures of 44 by 32, the one shown whole and ringed in white, the others at 60%. - To what reads the tree its buttons are
buttons called by their labels. - A renderer that draws another lightbox has
view.top(),view.stage(),view.caption(),view.filmstrip(),view.panel()(the three with the keys) andview.dismisser().
Gallery
Section titled “Gallery”Pictures in rows, each in a room of one shape, with one lightbox for them all; a gallery that chooses keeps which of them are chosen.
use lurq::ui::{Gallery, Picture};
// A press of a picture opens it in a lightbox that holds them all.Gallery::new(photos.iter().map(|photo| Picture::from_file(&photo.path).label(&photo.name))) .columns(4) .max_shown(8);
// chosen: Signal<Vec<PhotoId>>. A press chooses, Enter opens.Gallery::keyed(photos.iter().map(|photo| (photo.id, Picture::from_file(&photo.path)))) .selectable(true) .selected(chosen.clone());| Builder | |
|---|---|
new(pictures), picture(Picture), pictures(..) | The pictures, told apart by their place |
keyed(items), item(key, Picture) | The pictures, each with a key of the app’s (GalleryKey: Clone + PartialEq + Send + Sync): what is chosen is a list of those keys, which stays right when the pictures are put in another order |
columns(usize), min_picture_width(f32), gap(f32), aspect_ratio(f32) | The most pictures in a row (4); the least width of a picture (92, the board’s thumbnail), which takes columns away as the room narrows, down to one, and which 0 turns off; the room between them across and down (8); and the width of a picture’s room to its height (92 to 68). The room is measured before paint: the first frame has the rows of the settled one. A row the pictures do not fill keeps its empty rooms: its pictures are as wide as the others |
width(Length) | How wide the gallery is: all the room there is unless told, and never wider than its room. The pictures share it |
size(PictureSize) | The form of its pictures: Sm unless told |
max_shown(usize), more_text(Fn(usize) -> String) | The most pictures it shows: with more, the last one shown lies under a veil that says how many more there are, itself among them (“+5”). A press of it opens that picture in the lightbox, which holds every picture |
selectable(bool), selected(Signal<Vec<K>>), selected_controlled(keys, on_change), on_selection_change(Fn(&[K])) | Pictures that can be chosen, and the keys of the ones that are. Without a signal the gallery keeps them |
lightbox(bool), open(Signal<Option<usize>>), on_open_change(Fn(Option<usize>)) | Whether a picture opens in the lightbox (it does unless told), and which one is open, None while it is closed |
on_select(Fn(usize)) | A press of a picture, with its place, in a gallery that neither chooses nor opens |
label(&str), disabled(bool) | What it is called to tooling; and a gallery that takes nothing, its pictures at half the opacity |
state(name, on), style(part, ..), rules(&recipe), id, key | As a button has them. id is the id of the gallery; its pictures are <id>-0, <id>-1, … |
- It is a component wherever it is put, as a picture is: it keeps which picture is open, and what is chosen where the app gives no signal.
- Each picture is the app’s, without what lies over it (its bar, its badge, its own press and its own lightbox): the gallery gives it its press, its mark and its place in the lightbox. Its title and description are what the lightbox says under it.
- In a gallery that chooses, a press chooses a picture and takes it out again, and Enter opens the one with the focus; the picture that stands for the rest opens and is not chosen.
- Tab reaches the gallery once, and the arrows move the focus among its pictures, across and down.
- Parts:
GalleryPart::Root,Row,Cell. States:GalleryState::Selectable,Disabled. What a picture looks like in it is the picture’s recipe:.rules(..)on the pictures the app gives. - To what reads the tree it is a
listof pictures, or alistboxthat takes several where it chooses. - A renderer that draws another gallery has
view.render()and the parts’ styles; the rows are offlex(1)rooms with the ratio, so a picture is as wide as its share.
Carousel
Section titled “Carousel”Slides one after another in a room that shows one, or a few, at a time: turned by the round buttons beside them, the dots under them, the arrow keys, a swipe or a drag.
use std::time::Duration;use lurq::ui::{Carousel, Picture};
// Pictures as wide as the room, the first after the last.Carousel::new(photos.iter().map(|photo| Picture::from_file(&photo.path).aspect_ratio(16.0 / 9.0))) .wrap(true) .label("Photos");
// Three cards in view, turning by itself every five seconds.Carousel::new(cards) .per_view(3) .autoplay(Duration::from_secs(5)) .index(shown.clone());| Builder | |
|---|---|
new(slides), slide(element), slides(..) | The slides: any elements, each laid out as wide as its room |
index(Signal<usize>), index_controlled(index, on_change), on_index_change(Fn(usize)) | Which slide it is at, counted from 0: the first one shown. Without either the carousel keeps it and starts at the first |
per_view(usize), gap(f32) | How many slides the room shows at once, each as wide as its share (1); and the room between two (12). A turn moves by one, and the last few slides are one place |
wrap(bool) | Whether the first slide comes after the last, and the last before the first |
arrows(bool), dots(bool) | The round buttons beside the slides and the dots under them: both show unless told. With one place there are no dots |
autoplay(Duration) | Turns to the next slide by itself, from the last to the first. It waits while the pointer is over it and while the focus is in it from the keyboard, and stops for good once a person turns it |
width(Length) | How wide it is, its buttons with it: all the room there is unless told, and never wider than its room. The slides share what the buttons leave |
label(&str), previous_label(&str), next_label(&str), slide_label(Fn(usize, usize) -> String) | Its words to tooling: “Carousel”, “Previous slide”, “Next slide”, “Slide 2 of 4” |
disabled(bool), state(name, on), style(part, ..), rules(&recipe), id, key | As a button has them. id is the id of the carousel; its parts are <id>-previous, -next, -viewport, -slide-<n>, -dot-<n> |
- It is a component wherever it is put, as a picture is: it keeps which slide it is at.
- A press of a round button turns by one, a press of a dot goes to its place; a turn takes the slides there over a few frames, at once with motion reduced. A finger swipes a page at a time, as many slides as are shown. A drag of the mouse carries the slides, and let go a fifth of a slide away it goes on to the next. A trackpad scrolls them sideways and they come to rest on a slide.
- Keys: Tab reaches a round button, and the left and right arrow keys on it turn to the slide before and after; Tab reaches the dots once, the arrow keys move among them and Enter or Space goes to the one with the focus. A button that has nothing more to turn to takes nothing, and the focus it had goes to the other one. The slides that are not shown take neither the focus nor the pointer.
- Parts:
CarouselPart::Root,Track,Viewport,Slide,Arrow(the round buttons, which are design-system buttons,Outline, round),Dots,Dot,DotMark. States:CarouselState::Current(the dot of the place it is at),Disabled. - In the design the buttons are outline buttons of 36 with arrows of 16, 12 from the slides; 12 under the slides
the dots are 6 across, 6 apart, in
Input, the current one inPrimary. A dot is pressed in a room 3 larger on every side. - To what reads the tree it is a
regiondescribed as a carousel, each slide agroupdescribed as a slide and called by its label, the dots atablistoftabs. - A renderer that draws another carousel has
view.previous(),view.next(),view.viewport()(the slides, with what turns them) andview.dots().
QR Code
Section titled “QR Code”A text an app gives, drawn as a code a phone’s camera reads: an address to open, a code to pair a device, a ticket.
use lurq::ui::{QrCode, QrLevel};
QrCode::new("https://lurq.dev/pair?code=7F3K-92QD").label("Pair your phone");QrCode::new("TICKET-2026-11-16-0042").level(QrLevel::Quartile).length(220.0).quiet_zone(4);QrCode::new(address).media(logo);| Builder | |
|---|---|
QrCode::new(text) | The code of the text’s UTF-8 bytes, in the smallest version (1 to 40) that holds them |
level(QrLevel) | How much can be lost and the code still read: Low (7%), Medium (15%, the default), Quartile (25%), High (30%) |
length(length) | The side of the card, its padding included: 160 unless the app or a recipe says another |
quiet_zone(modules) | Modules of light around the code inside the card’s padding: none unless the app says |
media(element) | A logo over the middle, in a well of the light fill; the code is made at High |
label(&str) | What tooling calls it: “QR code” unless the app says what it is for |
locale(&Locale) | The words it speaks in, what tooling calls it, in place of the app’s (App::set_locale(Locale::for_tag("uk")), English where it set none), whose words are Locale::display. A label told by itself stays |
state(name, on), style(part, ..), rules(&recipe), id, key | As a button has them |
- It is dark on light in the light look and in the dark one alike, as the design draws it: a phone reads a code dark on light, and not every phone reads it the other way. Its fills are the roles of its recipe read in the theme’s light palette (
Theme::palette_color_for(Appearance::Light, role)): the cardBackground, the modulesForeground. Its edge is the window’sBorder. - The modules are as large as fit in whole logical pixels, and the code stands in the middle of the room inside the card’s padding. The card is drawn with
.snap_to_pixels(true), so every module’s edge is on a whole device pixel: at 100% and 200% every module is as wide as the next, at 150% a module of 5 is 7 or 8 device pixels, and two modules side by side meet with no seam. A run of dark modules, and the same run in the rows under it, is one box. - The encoder is lurq’s own, byte mode at every version and level, with the mask that scores best: no dependency, in every build and in the browser. A higher level is taken where it fits in the same version. A text too long for the level asked for is drawn at the highest level that holds it; one no level holds (over 2953 bytes) draws the card empty.
QrMatrix::encode(text, level)gives the modules themselves, to print or to draw another way. - The card’s padding of 10 is light, and is the quiet zone a phone needs where the modules are small; a code of large modules, or one that is printed, takes
quiet_zone(2)toquiet_zone(4). - A logo’s well is a fifth of the code’s side, an odd number of modules across so that it sits on the middle module, or the logo’s size with the well’s padding where the logo is larger: a logo larger than a fifth of the side may leave a code no phone reads.
- To tooling it is an image (
img) called by its label, whose description is the text, also where no code holds the text. - Parts:
QrCodePart::Root(the card),Module(a dark module),Media(the logo’s well). State:QrCodeState::Media. - In the design the card has an edge of 1 inside it in
Border,radius-lgcorners and 10 of padding, white, with modules of near black. The board draws eleven modules of 7, a picture of a code: a code of a real text has 21 or more, so the card is 160 by default. The board draws no logo, no loading and no expired code.
Watermark
Section titled “Watermark”A text, or a picture, repeated across what it covers, turned and faint, over the content: who a shared screen is shown to, a draft, a confidential report.
use lurq::ui::Watermark;
Watermark::new("lurq internal").child(card);Watermark::new("ivan@lurq.dev · 16 Nov 2026").child(page);Watermark::new("Draft").angle(-35.0).gap(16.0, 24.0).child(page);Watermark::new("lurq").media(logo).child(report);| Builder | |
|---|---|
Watermark::new(text) | The marks of a text |
child(element), children(elements) | What it covers; the watermark is as large as that |
media(element) | A picture repeated in place of the text, turned and faint as the text would be |
gap(x, y) | The room between one mark’s box and the next, across and down, before they are turned: 27 and 29 |
angle(degrees) | Clockwise where more than nothing: -20, rising to the right |
offset(x, y) | Where the first mark’s box is from the top left: -20 and 18 |
stagger(x) | How much further along every other row is: 40 |
state(name, on), style(part, ..), rules(&recipe), id, key | As a button has them |
- The marks take nothing from the content: their layer is hit by no pointer, so the content is pressed, selected and scrolled through them, and it says
a11y_hidden, so tooling reads the content and not the marks (see the MCP page). The layer’s id is the watermark’s with-layerafter it. - The mark is in the tree once; the engine paints it again across the layer (
.repeat(Repeat)), only where it can be seen. Over a page of any length in a scroll a watermark costs the marks in view, scrolling builds nothing again, and what is laid out again is the mark when its text or look changes, and the layer when the size of what it covers does. - A mark’s glyphs are drawn at its angle (
TextTransformMode::Rasterized), so it is sharp at every scale. Its color isForegroundat 0.12: dark on the light look, light on the dark one. - Parts:
WatermarkPart::Root(what holds the content and the layer),Layer,Mark(its type, color and faintness). State:WatermarkState::Media. The board’s numbers areWATERMARK_GAP,WATERMARK_ANGLE,WATERMARK_OFFSETandWATERMARK_STAGGER. - In the design the marks are “lurq internal” in the sans of 12, medium, in
foregroundat 0.12, turned 20 degrees counter-clockwise, 96 apart along a row and 44 from row to row, every other row 40 further along, over a card of 220 by 120 with an edge andradius-lgcorners. The card is the content it covers, not the watermark’s: a watermark draws no box of its own.
Link Preview
Section titled “Link Preview”What a link says about itself, shown before it is followed: the site with its icon, the title, a line of the description and the picture, as one link. A card, a row for lists and messages, and a link of 24 that stands in a sentence.
use lurq::ui::{LinkPreview, LinkPreviewVariant};
// What the page says, fetched.LinkPreview::new("https://lurq.dev/docs/layout");// The app's own title over the page's; the rest is fetched.LinkPreview::new(url).title("Layout, the guide");// Everything given: nothing is fetched.LinkPreview::new(url).title("Layout in lurq").description("Rows, columns and gaps.").site("lurq.dev").no_image().no_icon();// A row, and a link in a sentence.LinkPreview::new(url).variant(LinkPreviewVariant::Compact);LinkPreview::new(url).variant(LinkPreviewVariant::Inline);// In a message being written: a close drops it.LinkPreview::new(url).on_remove(move || draft.drop_preview());| Builder | |
|---|---|
LinkPreview::new(url) | The address. What the page says about itself is fetched and shown, the skeleton while it is read |
title(&str), description(&str), site(&str) | Shown in place of the page’s, one by one; what is not given is still fetched. The site is the domain of the address (no www.) where neither names one |
image(..), icon(..) | The picture and the site’s icon in place of the page’s: an address, a resources::Source, or a ui::Picture (LinkImage) |
no_image(), no_icon(), no_site() | None of it, whatever the page has: the text alone, the link mark, the title alone |
video(seconds) | A video, its length in seconds where it is known: the play mark and the length over its picture. A page that gives og:video or a kind of video.* is one by itself |
variant(LinkPreviewVariant) | Card (360, the default), Compact (a row of 432), Inline (24 high) |
fetcher(impl LinkFetcher) | What fetches the page for this preview, in place of the app’s (resources::set_link_fetcher) and of lurq’s own: any Fn(&str) -> LinkFetch. It is asked off the UI thread and may block; what it holds (LinkFetcher::held) is shown in the first frame. shared_fetcher(Arc<dyn LinkFetcher>) shares one |
on_open(Fn(&str)) | Told the address on a click, Enter or Space, in place of opening it in the browser |
on_remove(Fn()) | Gives it a close button, a stop of Tab of its own after the link: the app takes the preview out of what it shows |
return_focus(&ElementRef) | Where the focus goes once the close is pressed: the draft’s input. Without one it goes on to what follows the preview in the order of Tab, or to what comes before it where nothing follows (FocusHandle::focus_onward), never to nothing |
width(length) | A width of its own in place of the form’s; never wider than its room |
loading(bool) | The skeleton, whatever is known: an app that reads the page itself and has nothing to give yet |
label(&str), no_preview_text(&str), remove_label(&str), locale(&Locale) | What tooling calls it in place of its title; “No preview for this page.” and “Remove preview”, which are Locale::display’s unless told |
disabled(bool), state(name, on), style(part, ..), rules(&recipe), force(..), id, key | As a button has them. id is the link’s; the close button is {id}-remove |
- It works from the address alone. As it renders it asks its fetcher for the page’s
resources::LinkMetaand is drawn again when the fetch comes further. When every field the form shows is given (the title, the description and the site, the picture and the icon given or said to be none; an inline one shows no description and no picture) the fetcher is not asked. lurq’s own fetcher reads the start of the page through the app’s loader and keeps what it found in memory by the address (link previews); it needs the featurehttp. The gallery gives its previews a fetcher of its own and fetches nothing unless told. - A page that tells nothing (no title, no description, no picture), one that could not be read, and every page in a build without
httpor in a browser, is its address (without the scheme), the link mark, and a line under it: “No preview for this page.”, or what went wrong in the locale’s words (DisplayWords::link_error: “The page was not found.”, “The site answered 503.”). What the app gave stands over it. A page read that names no icon has its site’s/favicon.icotried, through the same loader and kept by it as any load; a picture or an icon that does not load is left out, and the link mark stands for the icon. - It is one link. A click, Enter and Space open the address with
open_url, unlesson_openis given; a disabled one is no stop of Tab and opens nothing. To tooling it is alinknamed by its title (or its label) and described by its site, its description and, for a video, “Video, 4:10”. Under the pointer it lifts (a card to the medium shadow) on the hover’s veil and its title is underlined; from the keyboard it has the ring. - Its text has a rule for its room: in a card the title and the description each end in an ellipsis after two lines, in a row after one; an inline one’s title ends in an ellipsis and its site keeps its room. Each form is as wide as the board draws it and never wider than its room; the skeleton’s lines are no wider than it.
- In a sentence, an inline one is an object of a rich text (elements in a line):
Text::rich([.., RichTextSpan::object(body), ..]).object(LinkPreview::new(url).variant(LinkPreviewVariant::Inline)). It is as wide as it is, wraps with the words, and the line keeps its height. A selection over it copies[title](url)(LinkPreviewView::copy_text), its address alone where the page told nothing. - It is a component of its own, mounted where it is converted into an element (
mount(ctx)mounts it at once): it keeps the fetch, whether the pointer is on it, and a picture that did not load.build(theme)is the still picture of what it was given, with nothing fetched, for a test. - Parts:
LinkPreviewPart::Root(the link),Media(the box of the picture),Play,PlayIcon,Length,Text(the column of the site, the title and the description),Site,Icon,Domain,Title,Description,Skeleton,Close,CloseIcon. States:LinkPreviewState::Loading,Media,Video,Empty,Removable,Disabled. - In the design a card is 360 in
Cardwith an edge ofBorder,radius-xlcorners and the small shadow; its picture is 360 by 188 (LINK_PREVIEW_PICTURE_RATIO) with a line under it, its text padded 12, 16, 14 and 16 with 6 between: the site in 12 ofMutedForegroundafter its icon of 16 (radius-sm), the title 14/500 at 1.4, the description 13 ofMutedForegroundat 1.5. A video has the play mark of 48 (a glyph of 20, white on black at 0.6) in the middle of its picture and its length in mono 11 on a dark tag 8 from the lower end; the close of a card in a composer is a disc of 28 on its picture, 8 from the top end. The compact row is 432, padded 12 with 12 between, the text (4 at its start, 4 between) beside a picture of 72 (radius-md); the inline link is 24 high withradius-mdcorners, padded 5 and 8 with 6 between, its title 13/500 inForegroundand its site 12 ofMutedForeground. While the page is read the skeleton’s lines stand for the text: 88 by 10, the width by 14, the width by 12 and 168 by 12 in a card, 88, 232 and 168 in a row, 10 apart; a square of 14 and a line of 96 in a sentence.
Action Sheet
Section titled “Action Sheet”On a phone, the actions on something, risen from the bottom of the screen over a scrim, and Cancel under them.
use lurq::ui::{ActionSheet, MenuItem};
// open: Signal<bool>. An option does what it does and closes the sheet.ActionSheet::new(open.clone(), [ MenuItem::new("Save to library").on_select(save), MenuItem::new("Duplicate").on_select(duplicate), MenuItem::new("Delete photo").destructive(true).on_select(delete),]).title("Photo options");| Builder | |
|---|---|
new(open, items), item(MenuItem) | Open while the signal says so, with its options: what an item says, whether it destroys something or is disabled, and what choosing it does. An icon, a shortcut and a submenu of an item are not shown |
title(&str) | What the sheet is about, over its options |
cancel_label(&str) | What Cancel says: “Cancel” |
on_dismiss(Fn()) | Told when it is closed with no option: Cancel, a press on the scrim, Escape |
inline(bool) | The sheet where it is declared, open or not, without the scrim: for a gallery, a screenshot, a test |
state(name, on), style(part, ..), rules(&recipe), id, key | As a button has them. Its options are <id>-option-<n>, Cancel <id>-cancel |
- It rises from the bottom as the scrim fades in, and goes down as it fades out. It takes the focus as it opens and gives it back as it closes; the arrow keys move among the options, and Enter and Space choose.
- Parts:
ActionSheetPart::Scrim,Root,Options,Title,Option,Label,Cancel,CancelLabel. States:ActionSheetState::Destructive,Disabled. - In the design the options are a card in
Cardwith a line ofBorderand the large corners, 8 in from the screen’s sides and bottom: the title 13 inMutedForeground, 12 over and under; options of 56 with a line over each and their words 17 in the middle, inForegroundorDestructive; Cancel 8 under them, a card of its own, 17 semibold. The scrim isScrim. - To what reads the tree it is a
dialogcalled by its title, its options and Cancelbuttons.
Tab And The Design System’s Controls
Section titled “Tab And The Design System’s Controls”A plain lurq::components::Button is a stop of Tab only inside a form or with a tab_index of its own. A control of the design system, a button, a toggle, a link, the track of a switch, the box of a checkbox, an input, is a stop wherever it is, in the order of the tree; a disabled one is passed by.
What is one choice or one bar is one stop, and the arrow keys move within it (focus groups): a radio group and a segmented control, where the choice follows the focus, and a toggle group, where Space turns the toggle the focus is on. In a button group every button is its own stop, as each is its own action, and the arrows move between them as well.
A Component That Holds Another
Section titled “A Component That Holds Another”A group does not draw its buttons: it holds them, and says what they are in its place. Its recipe has a part for that (ButtonGroupPart::Item), and ResolvedRecipe::rules_for(part, inner) turns what the recipe has for it, at rest and in each interaction, into rules for a part of the inner component, which the group lays over the theme’s recipe for that component (Button::rules):
let recipe = theme.resolve::<ButtonGroup>(&case, None);let item = recipe.rules_for(ButtonGroupPart::Item, ButtonPart::Root);let button = button.rules(&item); // over the theme's recipe for a button, under the button's own styleSo a theme restyles a button in a group by patching the group’s recipe, and a button elsewhere is as it was.
A Component Of Your Own
Section titled “A Component Of Your Own”A component of an app is themed the same way when it implements Themed: a name the theme keeps its recipe under, the type of its renderer, and its recipe when the theme says nothing about it.
use std::sync::Arc;use lurq::{node::Element, ui::{Case, Recipe, Themed, current_theme}};
struct Tile;
impl Themed for Tile { const NAME: &'static str = "tile"; type Renderer = Arc<dyn Fn(&str) -> Element + Send + Sync>;
fn recipe() -> Recipe { Recipe::new().base("root", |s| s.padding_x(16.0).padding_y(12.0)) }}
fn tile(title: &str) -> Element { let theme = current_theme(); let recipe = theme.resolve::<Tile>(&Case::new(), None); let root = recipe.part("root"); lurq::components::Column::new().part(&root).child(root.text(title)).into()}theme.patch_recipe::<Tile>(...), set_recipe, a bare theme and in_theme then reach it as they reach lurq’s own.
A component says what a recipe styles of it: Themed::parts() and Themed::states(), each a Declared, the names and the Rust that writes them. lurq’s own give their *Part and *State enums (names! gives each a declared(): fn parts() -> Declared { SwitchPart::declared() }); one that says nothing has the parts and the states its recipe names. A tool reads them: the gallery’s playground lists them in its Styling tab. A builder of a component of one’s own that has rules and state implements Styled with them, and is styled by what styles lurq’s.