Resources And Media
Resources And Media
Section titled “Resources And Media”Media APIs are feature-gated. image and canvas are in lurq’s default features; the rest an app turns on.
| Feature | Public APIs |
|---|---|
image (default) | Image, ImageData, StreamingImage, Video, raw RGBA/native image transport, image decoding and image-backed style helpers. |
canvas (default) | Svg, SvgData, beside the Canvas 2D. |
media | Playing a video or a sound (lurq::media, the players’ source), and its events. |
http | Addresses on the network, for everything that loads: the client and its TLS. A file, bytes and a resource of the app are loaded by every build. Until 0.63 it was resources. |
markdown | Markdown parsing and Markdown::mount. |
The raw transport (ImageData, StreamingImage) is lurq’s internal raster feature, which image, canvas and media each turn on.
App owns the glyph engine. Load fonts before running the window.
let mut app = lurq::app::App::new();
app.load_font_file(std::path::Path::new("assets/Inter.ttf"));app.load_fonts_dir(std::path::Path::new("assets/fonts"));app.register_font("ui", "Inter");App::load_font(bytes) loads a font from memory: one put into the binary with include_bytes!, or one a page fetched.
A family may also be a CSS generic family ("serif", "sans-serif", "monospace", "cursive", "fantasy"), drawn with the platform’s font for it; see Generic Families and GenericFamily for the fonts of each platform. A bundled font replaces one by an alias of the keyword: app.register_font("monospace", "JetBrains Mono").
App::set_generic_family(generic, family) names the font a generic family draws with, in place of the one chosen from the system’s fonts. GenericFamily::SansSerif is also the font of text with no family, so this is how an app draws all its text in a font it ships:
use lurq::layout::text_style::GenericFamily;
app.load_font(include_bytes!("../assets/fonts/Inter.ttf").to_vec());app.set_generic_family(GenericFamily::SansSerif, "Inter");A browser has no system fonts a page can read: an app that runs in one loads its fonts and names the sans-serif one at least. See Web.
Hinted Fonts
Section titled “Hinted Fonts”Text is drawn unhinted: a letter falls at any fraction of a pixel, and looks the same wherever it falls. An icon font is the opposite case. Its glyphs are drawn on a pixel grid, and a stroke a pixel and a half wide spread over three pixels is a blur. Load such a font with load_hinted_font:
app.load_hinted_font(include_bytes!("../assets/icons.ttf").to_vec());Its glyphs are then drawn grid-fitted: at the nearest whole pixel size and position, with the font’s TrueType hints applied along both axes. The font has to carry hints for this to do anything, and to ask for native ClearType in its prep program for the hints along x to count. A glyph under a transform, or in a text that is not snapped to pixels, is drawn unhinted like any other.
Text uses TextStyle.
use lurq::{ components::Text, layout::text_style::{FontStyle, FontWeight, TextStyle}, node::color::Color,};
Text::styled( "Hello", TextStyle { font_family: "ui".into(), font_size: 18.0, line_height: 1.25, weight: FontWeight::Bold, style: FontStyle::Normal, color: Color::from_hex("#e5e7eb"), ..TextStyle::default() },)Images
Section titled “Images”With image, load from bytes, files, or raw RGBA.
use lurq::{components::Image, images::ImageData};
let image = ImageData::from_file("assets/photo.jpg").unwrap();Image::new(image).size(240.0, 160.0)Supported formats come from the image dependency configuration: PNG, JPEG, WebP, GIF, BMP, and TIFF. GIF and animated WebP preserve animation frames.
Raw RGBA needs any of image, canvas or media:
let pixels = vec![255; 64 * 64 * 4];let image = ImageData::from_rgba(pixels, 64, 64);Streaming RGBA uses a stable image identity and uploads new pixels when the buffer version changes:
use lurq::{components::Image, images::StreamingImage};
let stream = StreamingImage::new_rgba(vec![0; 64 * 64 * 4], 64, 64);
stream.update_rgba(|pixels| { pixels[0] = 255; pixels[1] = 128; pixels[2] = 0; pixels[3] = 255;});
Image::new(stream.image_data())Runtime Images
Section titled “Runtime Images”An image decoded at runtime from encoded bytes or a file, for attachments, thumbnails and screenshots that are not resources of the app:
use lurq::{components::{Image, Rect, Text}, images::ImageKey, node::BackgroundSize};
Image::from_bytes(attachment.bytes.clone()) .cache_key(ImageKey::new(attachment.hash)) .downscale_to(256, 256) .fit(BackgroundSize::Cover) .placeholder(Rect::new(96.0, 96.0).background("#374151")) .error_view(|error| Text::new(error.to_string())) .size(96.0, 96.0) .rounded(8.0)Image::from_bytes(bytes) decodes PNG, JPEG, the first frame of a GIF or WebP, BMP and TIFF; Image::from_file(path) reads the file first; Image::from_source(source, key) takes either with a key. The decode runs on worker threads, off the UI thread: the node shows its placeholder (and its own background) until the pixels are there, then the image, and the error_view built from the ImageDecodeError for a broken file, instead of a panic. downscale_to(width, height) caps the decoded size, keeping the aspect ratio and never upscaling, so a thumbnail of a 4K screenshot does not keep its 30 MB of RGBA. fit places the pixels in the node’s box: Stretch (the default, as Image::new always drew), Contain fits the whole image centered, Cover fills the box and crops the overflow; it works on every image node.
Decoding runs on worker threads, and in a browser on the page’s one thread, after the turn of the loop that asked for the image.
Decoded pixels are kept in the process-wide cache, lurq::images::decoded_images(), keyed by content and size cap: from_bytes hashes the bytes (ImageKey::of_bytes), from_file keys the path with the file’s size and modification time (ImageKey::of_path), and an app that stores a hash of its own builds the node with Image::from_source(ImageSource::Bytes(arc), ImageKey::new(hash)), which neither hashes nor copies the bytes (cache_key replaces the key after from_bytes has hashed). A chat laid out again, or a VirtualizedList row built again as it scrolls back in, finds its image ready in the first pass and decodes nothing. The cache keeps at most DecodedImages::budget() bytes of RGBA (128 MiB by default, set_budget), dropping the least recently used ready images; a node that still shows one keeps it. decoded_images().state(key, cap) reads an entry without decoding, insert puts pixels the app decoded itself, and decode_image(&source, cap) decodes on the calling thread. A test waits with lurq::images::wait_for_decoded_images(timeout); see Testing.
Clipboard
Section titled “Clipboard”With clipboard, lurq::clipboard reads and writes the OS clipboard. Besides the text functions (copy_to_clipboard, read_from_clipboard, clear_clipboard), read_clipboard() reads everything it holds at once as a ClipboardContent: the text, the image a screenshot tool or a browser put there (Windows CF_DIBV5/CF_DIB, macOS public.png/public.tiff, as RGBA), and the files copied in Explorer or Finder (CF_HDROP, file URLs). A clipboard may hold text and an image at once; kinds() tells which.
use lurq::clipboard::{copy_image_to_clipboard, read_clipboard};
if let Some(content) = read_clipboard() { if let Some(image) = content.image_content() { let png: Vec<u8> = image.to_png()?; // to store it } for path in content.file_paths() { // a file copied in Explorer or Finder }}copy_image_to_clipboard(width, height, &rgba);ClipboardImage::from_rgba(width, height, rgba) builds the image a test or an app pastes; copy_files_to_clipboard(&paths) puts file paths there. A paste into a text input delivers the same ClipboardContent through a PasteEvent; see Paste.
In a browser a page writes the clipboard at once and reads it only by waiting: copy_to_clipboard writes the system clipboard, the reading functions return what the page copied last, and only text crosses. A paste shortcut does read the system clipboard. See Web.
A Color From The Screen
Section titled “A Color From The Screen”lurq::eyedropper::EyeDropper lets a person pick a color from anywhere on the screen: another app’s window, a picture, the app itself. The pick runs off the loop, and its future does not borrow the window, so it is what a ctx.future_action runs, as the file dialog is:
use lurq::eyedropper::EyeDropper;
let window = ctx.window();let pick = ctx.future_action(move |()| EyeDropper::new().pick(&window));// In a handler: `pick.run(())`. `pick.state()` then holds `Ok(Some(color))`, `Ok(None)` where the person// gave up, or `Err(Unsupported)` where the platform has no picking.While it picks, the pointer is a cross and a loupe follows it: the pixels around the pointer magnified, the one taken outlined in the middle, its hex beside it, in the popover colors of the theme given with .theme(&theme). A press takes the color; Escape, the right button or another window taken to the front gives up. The arrow keys move the pointer by a pixel, by ten with Shift, and Enter or Space take the color, for the pixel a hand cannot hit.
| Platform | |
|---|---|
| Windows | A thread of its own with the platform’s means, as PowerToys’ color picker and a browser’s eyedropper do: a window over every monitor, all but transparent, takes the pointer and the keys, and a small layered one shows the loupe, drawn whole into a bitmap and given to it with its place in one call, so it never shows half drawn. Both are kept out of what is read of the screen (WDA_EXCLUDEFROMCAPTURE), so the pixels under the pointer are read live with GDI as it moves, a plain read of the composed desktop (not CAPTUREBLT, which hides the cursor for each read) that has other apps’ layered windows in it; before Windows 10 2004 the screen is read once as the pick starts. The thread is aware of each monitor’s scale, so the pixel taken is the physical one under the pointer at 150% and across monitors of different scales, and the loupe is as large on each |
| macOS | The system’s own sampler (NSColorSampler), shown from the main thread: its own loupe, so .theme(..) is not used, and the system’s keys (Escape gives up). The color it gives is converted to sRGB |
| Linux, iOS, a browser | Not yet: EyeDropper::is_supported() is false and pick gives Err(Unsupported) at once; the color picker and the color field show no eyedropper |
EyeDropper::is_supported() is what a component asks before it shows an eyedropper; the color picker and the color field show theirs only where it is true. A test, or a tool driving the app, sets EyeDropper::stand_in(|| Ok(Some(color))), which answers the picks of its thread until the guard it gives is dropped. Setting LURQ_EYEDROPPER_SNAPSHOT in the environment takes the way of a system that cannot keep the windows out of a capture: to check it, and to see the loupe in a screenshot.
Resource Images
Section titled “Resource Images”With image, let the runtime load files relative to the resource root.
let mut app = lurq::app::App::new();app.set_resource_root(std::path::PathBuf::from("assets"));
let avatar = lurq::components::Image::from_resource("avatar.png");The first frame may render while the resource is pending. The loader caches successful results according to ResourceConfig.
Background images use the same feature pair:
use lurq::{components::Rect, node::BackgroundSize};
Rect::new(320.0, 180.0) .background_image("hero.jpg") .background_size(BackgroundSize::Cover)Or use helper shortcuts:
Rect::new(320.0, 180.0).background_cover()Rect::new(320.0, 180.0).background_contain()Slider track and thumb styles can also use resource-backed background images:
use lurq::components::Slider;
Slider::new(value) .track(|style| style.background_image("ui/track.png").background_cover()) .thumb(|style| style.background_image("ui/thumb.png").background_cover())With canvas, construct SVGs from bytes or strings.
use lurq::{components::Svg, node::color::Color, svg::SvgData};
let icon = SvgData::from_str(r#"<svg viewBox="0 0 24 24"></svg>"#) .with_fill(Color::from_hex("#a855f7"));
Svg::new(icon).size(24.0, 24.0)With canvas and http:
Svg::from_resource("icons/search.svg").size(18.0, 18.0)SvgData supports fill, stroke, and opacity overrides.
Loading
Section titled “Loading”Everything that loads is given a Source, and the app’s Loader reads it: a picture, a video and a sound alike.
use lurq::resources::Source;
Source::file("photos/lake.jpg");Source::bytes(png_bytes);Source::resource("brand/logo.png"); // a path under the app's resource rootSource::url("https://example.com/lake.jpg").header("Authorization", "Bearer token");A header is on every request made for the source: the load of a picture, of a sound loaded whole, and each request a
video or a sound makes as it plays (a host that serves only its own pages wants its Referer, one that serves only
who signed in an Authorization). Headers for every address of a host are the loader’s rule, given once; a source’s
own come after the rule’s and take the place of one of the same name:
app.loader().headers(|address| { if address.starts_with("https://videos.example.com/") { vec![("Referer".to_owned(), "https://example.com/".to_owned())] } else { Vec::new() }});What a video or a sound reads as it plays:
- Windows: the app’s loader reads every address (
loader.open, below) and gives Media Foundation the stream, which only decodes: so the headers,allow, the proxy, the timeout and the cache on the disk hold for it as for a picture. Where it has nothing left to show and the part it needs is still on the network a quarter of a second on, the media waits (on_waiting_change) and its clock stands; a part the decoder reads ahead while it plays is no waiting. A read the server refuses on the way fails the media with what it answered (MediaError::Server(403)). It needs the featurehttp; a build without it has Media Foundation read the address itself, with no header. - macOS and iOS: the system’s player reads the address, given the headers (
AVURLAssetHTTPHeaderFieldsKey, a key AVFoundation reads that is not in its headers). Reading it through the loader, as Windows does, is still to come. How far it reads ahead is bounded as the loader’s reading is: until the media is first told to play, a second past where it stands, so a video opened ahead and left paused takes its start and no more; once it plays, ten seconds. Left to itself the system’s player reads on while it stands, and reads a playing video to its end as fast as the host gives it, which costs the radio, the battery and the person’s data, and takes a slow host’s bytes from the video that is to open next. - Browser: a page’s
<audio>sends the browser’s own headers and cannot be given others, and some (Referer) no page may set at all. The address is played without them, with one warning in the log.
A source has a key, which tells it from another: a file’s is its path with its size and the time it was changed,
bytes are hashed once, a resource’s and an address’s is their text. .key(hash) gives a key of the app’s own in
its place.
app.loader() is the app’s loader. It holds the resource root and what the network may do, reads on threads of its
own, makes one load of a source asked for twice, and stops a load nobody waits for any more:
use std::time::Duration;
app .loader() .root("assets") // what `Source::resource` is a path under .timeout(Duration::from_secs(10)) // of a load of an address; 30 seconds unless told .max_bytes(16 << 20) // the most `load` reads of one source; 64 MiB unless told .pool_size(6) // loads read at once, and HTTP agents kept; 4 unless told .allow(|address| address.starts_with("https://cdn.example.com/"));pool_sizeis how many loads are read at once, on as many threads of the loader’s own, or as many blocking tasks at a time of the app’s runtime where it gave one, and how many HTTP agents the loader keeps. A load of an address is lent an agent and gives it back when it ends, with the connections it opened kept open, so the next load of the same host, a picture of the same album, goes over one of them with no new handshake: a load is lent the agent that asked its host last. A reader of an address (loader.open, a video) asks over the agent it was lent when it was opened, every time. Told again, it is for the loads asked for from then on: those on their way end on the threads they were given, and an agent given back beyond the new size is let go.- Whose turn it is. Of the loads that wait for a free thread, the next one read is the one of the highest
priority, and among those the one asked for last, not the one that came first: in a long list scrolled fast,
what is on the screen now is read before what went by.
load.set_priority(LoadPriority::High)(orloader.load(&source).with_priority(..)) puts a load before the others,Lowafter them; it can be told again while the load waits. A mountedui::Picturegives its loadHighwhile any of its box shows in the list it scrolls in, andNormalwhen it does not. - A load nobody waits for is not read. A
Loaddropped by everyone that held it (the picture of a row that scrolled out of a virtualized list, a component that was unmounted) is let go a quarter of a second later: one that still waits its turn is never started, and the server is never asked; one being read stops at its next step. So a list scrolled past does not hold the pool. Asked for again, it is loaded as anything new is. allowsays which addresses may be loaded: every one the app asks for, unless told. One it refuses fails withLoadError::Deniedand nothing is sent. It is what keeps a text from a stranger, shown by the app, from fetching what the stranger chose.loader.load(&source)loads all the bytes of a source and gives aLoad. Itsstate()isLoading { loaded, total },Ready(bytes)orFailed(LoadError);wake_withis called when it ends and as it comes further. A load that failed stays failed, so that what asks for it again is told so and not sent to the network again;loader.forget(&source)forgets it, and the nextloadtries anew.loader.open(&source)gives aReader:len(),content_type(),read_at(offset, buf)andbuffered(), for what reads a part of a source and not all of it. A file, a resource and bytes are read where they are. An address is read by ranges as they are asked for, with the rule’s and the source’s headers and the loader’s timeout on each request, the two that follow fetched ahead and the last 16 kept.openasks for the first range and returns once its answer has come, so it blocks (call it off the UI thread): the answer gives the length and theContent-Type, and a server that refuses fails it there (LoadError::Status(403),LoadError::NotFound). A read that fails later gives anio::ErrorthatLoadError::fromturns into what the server answered, and the next read of the same place asks again. A server that reads no ranges is read from its start for each. What the cache on the disk keeps of the address is read from its file. It needs the featurehttp, and is not built in a browser (LoadError::Unsupported).- A read has its bytes as they come.
read_atgives what has come of a range and does not wait for the range to be whole: a decoder that needs the first 40 KB of a range of 1 MiB has them when they are there, and not a second and a half later on a host that sends 600 KB a second.buffered()says how far each range has come. - One request after the other, over one connection. A reader asks for the range a read waits for, and then, where it reads ahead, for what follows the last read, each request once the one before has ended, on the connection it ended on: no new handshake, and nothing ahead of the decoder while a read waits. A reader that reads ahead asks for its small first ranges in one request, as long as the largest range. A second request is made beside the first only for a read that waits for bytes the first is not bringing (a video sent to another place, an index at the end), and a request nobody waits for then stands still until that read has its bytes. It matters on a host that gives one client so much a second in all, however many connections it has: there the two ranges read ahead beside the one that was waited for shared with it what the host gave, and each paid a handshake of its own.
- The start is kept. When a reader of an address is dropped, the ranges it read whole from its start, 2 MiB of
them at most, stay in memory for five minutes, for the last 8 addresses. A reader of one of them starts with
that, with no request: a video closed and opened again a moment later (a page of a pager gone and come back)
opens at once, and asks the network for what follows.
loader.keep_starts(n)says of how many addresses, 0 for none, andloader.forget(&source)lets go of the start of one. - A connection ahead.
loader.connect(address)opens a connection to the host of an address before the first request to it, away from the caller: an app that knows the host of a video a moment before it makes the player spares the player the handshake, a quarter of a second on a host far away. It asks the host for the head of what is at the address (aHEADrequest with the rule’s headers, whose answer has nothing in it) and keeps the connection whatever the answer; an agent lets go of a connection nothing went over for a quarter of a minute. A host asked in the last ten seconds is not asked again, and nothing is sent to an addressallowrefuses. - The ranges grow. The first two are 256 KiB, each one after them twice the one before up to 1 MiB, and 1 MiB
from there on: what opens a video reads its start, and on a host that sends 600 KB a second a first megabyte
kept the first frame waiting two seconds, while what plays reads on, where larger ranges are fewer requests.
256 KiB is what Media Foundation reads of a file at a time, so a smaller first range is more requests for the
same bytes and no sooner.
loader.read_blocks(first, most)says others, for the readers opened from then on. - An index at the end. An MP4 file not written for the network has its index (
moov) after its pictures, and a decoder asks for it only after the start, one request after the other. The reader sees it in the first bytes of the first range and asks for the ranges of the index at once, beside the first. - Reading ahead can be turned off,
reader.read_ahead(false): the reader then fetches what is read and no more, until it is told to again, when it fetches what follows its last read at once. A media does so until it is first told to play (a video opened ahead). - What it asked for. With
lurq::resources=debugin the tracing filter every range request is a line: the address, the range, the bytes that came and the milliseconds it took. What a slow start is made of (the connection in the first request, the requests one after another) is read there. - The loader keeps no bytes of a load in memory once nobody holds it. What is decoded from them is kept by who
decodes: a picture’s pixels are in
lurq::images::decoded_images(). Of the addresses its readers read it keeps the start, as above.
What is loaded from an address is kept on the disk where the app gives a folder for it, and is then there for the next run of the app:
// The app's own cache folder: lurq picks none. Not called, nothing is written to the disk.let app = App::new().enable_media_disk_cache(cache_folder);let kept = app.loader().media_disk_cache();kept.budget(2 * 1024 * 1024 * 1024); // 512 MiB unless toldkept.forget(&source); // or `app.loader().forget(&source)`: it is loaded from its address againkept.clear();- A load of an address writes a file there, named by the source’s key and its length, and a load of the same source reads the file and asks the network for nothing. A file is written under another name and renamed when it is whole. One that is gone, or is not as long as its name says, is loaded again.
- Over the budget the file used longest ago is deleted. Only the cache’s own files are counted and deleted: the folder may hold other things.
- Nothing asks the server whether a file has changed, and nothing is let go for being old: an app that knows a source changed forgets it, or gives it a key of its own. What came with a header is kept as it came.
kept.holds(&source),bytes(),len(),folder()andis_on()say what it keeps. A folder that cannot be written is one warning in the log, and nothing is kept there.- A sound at an address plays from its file (playing a sound).
With the feature tokio, an app that gives its runtime (App::with_tokio_handle(handle)) has its loader read on
that: a load is a blocking task of the runtime, as many at a time as pool_size, and the loader starts no threads of its own. A
loader made by itself is told with loader.tokio_handle(handle). The runtime is to run for as long as the app
loads: a load given to one that has stopped fails with LoadError::Cancelled, and App::clear_tokio_handle()
gives the loader its own threads back.
A LoadError says why: NotFound, Denied, Status(code), TooLarge { limit }, TimedOut, Cancelled, Io, and
Unsupported, which is what a build that cannot load such a source answers. An address in a build without the
feature http is one: it compiles, and fails at run time with the reason and one warning in the log. In a browser
a file and an address are not loaded yet.
Media events
Section titled “Media events”A lurq::media::Media plays on a thread of its own (see playing a video). What
happens to it is told to the handlers an app adds, as a browser’s media element tells its events:
use lurq::media::Media;
let media = Media::open(app.loader(), &Source::file("clips/lake.mp4"));media.on_load(|info| println!("{:?} long, {:?}, sound: {}", info.duration, info.size, info.sound));media.on_error(|why| tracing::warn!("{why}: {}", why.detail().unwrap_or_default()));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}"));media.play();| Handler | Told |
|---|---|
on_load(Fn(&MediaInfo)) | Once it opened and is ready to play: duration (None for what has no end), size of its picture (None for a sound), whether it has sound |
on_error(Fn(&MediaError)) | Once it cannot play: a kind, which the locale says (MediaWords::error); detail() is what the system said, for a log. A media that failed stays failed: trying again is opening it anew |
on_started(Fn()) | Each time it really starts to play: it was told to, it does not wait for what it plays, and the first frame since is shown (for what has no picture, its sound is given to the output). After on_load, which is that it opened, and after on_playing_change(true), which is that it was told to play. Again after a pause, after it waited and after its end; not for a round of a looped media, which did not stop, nor when it is sent to another time while it plays |
on_ended(Fn()) | Each time it played to its end, again only after it played again. A looped media (media.set_looped(true)) is told at each end as it goes on from its start, and is not told it stopped playing |
on_playing_change(Fn(bool)) | Whether it plays, each time that changes once it opened: told to play or pause, it ended, it failed |
on_waiting_change(Fn(bool)) | Whether it waits for what it plays once it opened (an address read slower than it plays); opening is not waiting |
- On the UI thread. The media’s thread changes its state and wakes the loop of each window of the thread that
first listened to it; the window’s next turn (its pass, or the tick of its timers) compares the state with what it
last told and calls the handlers, before anything is rendered: a signal a handler sets is drawn in that frame. The
app polls nothing. A test’s tree tells them in its
pass. - Once each time, in order. In one turn they come as a media lives them: it opened, it waits or not, it plays or not, it ended, it failed. Told to play before it opened, it says it opened and then that it plays. What it did before a handler was added is told in the next turn; a handler added later hears what happens from then on.
- Many handlers. Each
on_*adds one, called after those before it. They live as long as the media. Media::on_changestays what it was: a call from the media’s own thread whenever it changed, with nothing said, for what draws it (a player renders again).
Link Previews
Section titled “Link Previews”What a page says about itself, its title, description, site, picture and icon, is read from the start of its HTML
and given to a link preview (ui::LinkPreview) as a LinkMeta. A preview asks a LinkFetcher for it off the UI
thread, on a few threads of lurq’s (in a browser, once the frame is drawn), and is its skeleton until the fetcher
answers: a fetcher may block, on a cache on the disk or a server of the app’s, and the window is drawn on. It is
woken when the fetcher has more, and asks again.
use lurq::resources::{LinkFetch, LinkMeta, LinkPreviewError, set_link_fetcher};
// What a page says, read from its bytes by a scanner of its head of lurq's own.let meta = LinkMeta::from_html("https://lurq.dev/docs/layout", &bytes);
// The app's own fetcher, for every preview that has none: any `Fn(&str) -> LinkFetch`.set_link_fetcher(|url: &str| match known_previews(url) { Some((title, site)) => LinkFetch::ready(LinkMeta::new(url).title(&title).site(&site)), None => LinkFetch::Failed(LinkPreviewError::NotFound),});LinkMeta::from_html(url, bytes)finds the<title>, OpenGraph’sog:title,og:description,og:image,og:site_name,og:type,og:videoandog:video:duration(andvideo:duration, or a schema.orgdurationsuch asPT4M10S), a Twitter Card’stwitter:title,twitter:descriptionandtwitter:image, the plain<meta name="description">, the<link rel="icon">andapple-touch-icon, and a<base>. OpenGraph comes before the Twitter Card, which comes before the plain title and description. Every address in it is made whole from the page’s (//,/,../). It stops at the end of the head or at the body, passes comments, scripts and styles by, and takes in its stride what a page gets wrong: attributes without quotes, tags in capitals, a head with no end, a tag cut by the end of what was read. It reads UTF-8, and the charset a<meta charset>or aContent-Typemeta names where it is Windows-1252 (ISO 8859-1), Windows-1251, KOI8-R or KOI8-U; any other is read as UTF-8.LinkMeta::is_empty()says the page told nothing a preview shows.PageFetcheris lurq’s own fetcher, one for the process: it reads the first 512 KiB of a page (head_bytes(..),DEFAULT_LINK_HEAD_BYTES) through the app’s loader withloader.load_start(&source, bytes), which reads the start of a source and ends there with no error, finds what the page says, and keeps that in memory by the address: a page shown in many previews is read once. A page that failed stays failed untilforget(url);clear()forgets every one. The loader’sallowandtimeouthold for it as for any load, and its disk cache neither keeps nor gives the start of a page. A text that is not an address is a resource of the app.- A preview’s fetcher is its own (
LinkPreview::fetcher), else the app’s (set_link_fetcher,reset_link_fetcher), else lurq’s;link_fetcher()gives the one in use. A fetcher is a type of the trait, told aLinkRequest(the address, the app’s loader, and the waker to call once it has more), or a function of the address. What a fetcher already holds, ready or failed, it gives without blocking fromheld(url), asked on the UI thread as the preview renders, and the preview shows it in its first frame and not after a frame of its skeleton;PageFetchergives the pages it keeps. A fetcher that blocks holds one of the threads previews ask on, and the previews after it wait for one.wait_link_fetches(timeout)waits for what the previews rendered on the calling thread asked, for a test or a tool that draws them headless. - What went wrong is a
LinkPreviewError:NotFound,Denied,TimedOut,Server(status),Network,Unavailable(a build withouthttp, a browser) andOther;detail()is what the connection said, for a log.Locale::displayputs each in words (DisplayWords::link_error). - Fetching a page needs the feature
http. Without it, and in a browser, every page isUnavailable, and a preview shows what it was given and the address.
Resource Loader
Section titled “Resource Loader”ResourceLoader is the loader before app.loader(), which the feature http keeps: it is polled, and a resource
image built with Image::from_resource, a background image and a resource SVG still use it.
ResourceLoader::load_resource(path, config) returns:
Pendingwhile async load is in progress,Loaded(Arc<Vec<u8>>)when bytes are ready,Error(ResourceError)for not found, network, OS, or unknown errors.
Local paths are resolved under App::set_resource_root(...) when set. Remote http:// and https:// URLs are loaded through ureq.
use std::sync::Arc;use lurq::resources::{LoadResourceResult, ResourceConfig};
let loader = lurq::resources::ResourceLoader::new();let path: Arc<str> = Arc::from("data.json");match loader.load_resource(&path, Some(ResourceConfig { ttl: 60, retries: 1 })) { LoadResourceResult::Pending => {} LoadResourceResult::Loaded(bytes) => println!("{} bytes", bytes.len()), LoadResourceResult::Error(error) => println!("{error:?}"),}Most app code should prefer the higher-level resource-backed Image and Svg constructors.
Markdown
Section titled “Markdown”Enable markdown to parse and render Markdown through a retained component:
use lurq::components::{Markdown, MarkdownProps};
Markdown::mount( ctx, MarkdownProps::new("# Notes\n\nRead the **release notes**.") .selectable(true) .on_link_select(|link| println!("{}", link.destination())),)Use MarkdownProps::style(...) for the base text style (the theme’s TypographyStyle::Article, 15 on lines of 1.65, where it gives none), .theme(...) for block styling, and .width(...) for a width constraint. Link callbacks decide how the application opens or routes destinations. The gallery’s Markdown page (in Data) shows every block.
MarkdownProps::build(theme), and Element::from(props), draw the document once with nothing kept: no link tooltips, every <details> as it begins, no jump to a footnote. Mounted, the component keeps what a person does to it.
The blocks
Section titled “The blocks”The document draws every block of the design’s (pencil/lurq-design-system.pen, Markdown):
- Headings in the theme’s type scale (
TypographyStyle::Heading1toHeading6): 30 bold, 24 with a line under it, 20, 16, 14, and 12 in capitals in the muted foreground. - Lists: a number at the end of a column of 18 in the muted foreground; a bullet of 5, a dot at the first level and a ring under it (a selection over a bulleted item still copies its
-). Tasks (- [ ],- [x]) are the checkbox’s look, a done one’s words in the muted foreground. A task’s box is read only, taking neither the pointer nor the focus, unless the app takes its change:.on_task_change(|index, checked| ..)is told the task’s index among the document’s tasks and whether it is checked now, and the app writes that into its source. - Quotes are
ui::Blockquote: a line of 2 at their start, their words 14 in italics in the muted foreground. Code blocks areui::CodeBlock: a bar named by the language, with the button that copies the code, over the code in the family of code, told apart by its language’s tokenizer and colored in the theme’s code colors (see Highlighting code). Both look as the theme’sblockquoteandcode_blockrecipes say, one look wherever they are. - Tables: a box of the middle radius, the header on the bar’s fill (
Bar: white in the light palette) over a line, every other body row striped inMuted, a line between two columns, the columns of one width and each aligned as its delimiter row says. - The rule (
---): a line of 1 in the border’s color. An image that stands alone: the image where the app draws images (image), or else a box of its place, with its caption under it: its title, or its words. - Admonitions, GitHub’s:
> [!NOTE],> [!TIP],> [!IMPORTANT],> [!WARNING],> [!CAUTION]on a quote’s first line. Each is aui::Calloutwith a bar, in the tone of its kind: info, success, neutral, warning, destructive. - Details:
<details>with a<summary>(onBar, edged by a line ofBorder), which opens and closes what it holds;<details open>is open to begin with. The parser reads them from the HTML blocks around the Markdown in them. - Footnotes: a reference is its number in the info color, numbered by the first reference to each, and goes to its footnote; the footnotes stand at the end of the document under a short rule, each with the way back to where the text first refers to it.
- In a sentence: code on the box of
ui::InlineCode, keys (<kbd>Ctrl</kbd>) on the box ofui::Kbd, struck words in the muted foreground, links in the info color at 500.
The parser reads them all from pulldown-cmark’s events: MarkdownBlock::Admonition with its MarkdownAdmonitionKind, MarkdownBlock::Details, and MarkdownInline::Kbd are new.
The theme
Section titled “The theme”ThemeMarkdown’s colors are the palette’s roles (TextColor::Palette) or colors an app gives (TextColor::Color): a document is drawn in the theme it is in, light and dark, and in a theme an app makes. Its sizes are the design’s, relative to the document’s text where they are of type (inline code is 13 where the text is 15). ThemeMarkdown::resolve(&palette) gives the theme with every role turned into the color the palette has for it.
By default the document fills its container’s width, and so does every block in it. .fit_content(true) sizes it to its content instead, like CSS width: fit-content; max-width: 100%, so a chat bubble hugs its message:
Column::new() .align_items(Alignment::End) // own messages on the right .child( Column::new() .padding(8.0) .background(bubble_color) .child(Markdown::mount(ctx, MarkdownProps::new(message).fit_content(true))), )- The document is as wide as its widest block (a short message as its longest line) and never wider than its container’s width, where its text wraps. Paragraphs, headings, lists, quotes and footnotes all size to their content; a long list item wraps beside its marker.
- Every block is then stretched to the document’s width, as CSS blocks are: a code block’s box and a rule span the widest block.
- A code block does not wrap: it is as wide as its longest line up to the container’s width, and a longer line scrolls inside its box, as when filling.
- A table still takes the container’s full width: its columns share that width so that they line up across its rows.
- An explicit
.width(...)still sets the document’s width. - In a
Column, the container’s width is the column’s. ARowgives its children unbounded width, so a bubble in a row needs.max_width(Dimension::Pct(100.0))(or aflex_shrinkfactor) for its text to wrap at the row’s width.
Code blocks
Section titled “Code blocks”A code block (ui::CodeBlock) never wraps its lines. A line wider than the block’s box scrolls sideways inside it: the box, its bar and the document keep their width, and the block’s scroll area shows its bar over the code while it overflows. Shift+wheel and a trackpad’s sideways swipe scroll the block; a plain or slightly slanted vertical wheel over it scrolls the page around it, as it always did, so a chat’s follow-to-end is not caught by a block that only overflows sideways. The block’s own scroll is kept across renders, keyed by the block’s ordinal among the document’s code blocks and its language: a streaming reply and paragraphs added around it keep its place (a code block inserted above it shifts the ordinals). A math block ($$) scrolls the same way. A block whose lines fit has no scrollbar. Selection and copy cross a scrolled block like any other block, the lines out of view included, and its language with them; the glyphs of the document’s controls (the copy button, a task’s check, an admonition’s icon) are never part of what a selection copies.
Highlighting code
Section titled “Highlighting code”A code block, Markdown’s fenced code, ui::InlineCode given a language and a code field color their code the same way: a tokenizer tells the code’s tokens apart and names each, and the theme’s code colors draw each name. Neither needs the markdown feature (lurq::code).
A token’s name is dotted, as TextMate and tree-sitter name them: keyword, keyword.control, string, string.escape, number, comment, comment.doc, type, function, function.macro, variable, variable.builtin, constant, property, attribute, operator, punctuation, tag, regex, namespace, label (lurq::code::token has them as constants), and any other a tokenizer gives. A name the colors have nothing for is looked up dropping its tail: keyword.control.rust, then keyword.control, then keyword, then the code’s own color.
One tokenizer for each language. lurq registers its own at start, for Rust (rust, rs), TOML, JSON (jsonc), JavaScript (js, jsx), TypeScript (ts, tsx), shells (sh, bash, zsh, console), Python (py), CSS (scss, less), HTML (htm, vue), XML (svg), YAML (yml), SQL (postgres, mysql, sqlite) and Markdown (md). A language with none is plain text. An app registers its own for any language; one for a language that has one replaces it, lurq’s included, under each of its names, and whatever shows that language’s code is drawn again:
use lurq::code::{CodeToken, token};
// Any Fn(&str) -> Vec<CodeToken> is a tokenizer: here, every word that starts with `$` is a variable.app.register_tokenizer("dollars", |code: &str| { let mut found = Vec::new(); let mut at = 0; for word in code.split(' ') { if word.starts_with('$') { found.push(CodeToken::new(at..at + word.len(), token::VARIABLE)); } at += word.len() + 1; } found});
// Other names of the language, which a fence (```psql) may use.app.register_tokenizer_with_aliases("sql", &["psql", "postgres"], my_sql_tokenizer);- A tokenizer is a
lurq::code::Tokenizer(anyFn(&str) -> Vec<CodeToken>is one): its tokens are in bytes of the code, and need not cover it; what none covers is plain. Tokens that are empty, out of the code, off a character’s boundary or over another are left out. CodeTokenizer::new(h)makes one to keep and clone:CodeBlock::tokenizer(h.clone())gives a block its own over the registry’s, and what it gave for a code is not asked again.lurq::code::register_tokenizer,remove_tokenizer,tokenizer(language),knows(language),languages()andtokens(code, language)are the registry itself; it is the process’s, as an app is one.App::register_tokenizersays the same.- What a tokenizer gave is kept, by the tokenizer and the code (a few hundred codes, a few megabytes of them): a render that changes nothing of a block’s code does not tokenize it again, and a tokenizer registered in place of another forgets what the other gave.
- A Markdown fence’s info string is read up to its first space or comma:
```rust,ignoreis Rust.
lurq’s own are tables. One scanner reads every language from a CodeLanguage: its names and aliases, its words by name (.words(token::KEYWORD_CONTROL, &["if", "else"]), in any case for SQL), line comments and block comments (nested, and documenting ones), forms of strings (prefixes, raw strings with their #s, three quotes, escapes, a quote doubled), the forms of numbers, what makes a type (a capital), a namespace (a name before ::), a call (a name before (), a macro (name!), an attribute or a decorator (#[, @), a key (before : or =), a section ([table]), a variable ($HOME), a command, a tag. It reads line by line, from the state a line starts in (inside a block comment or a string an earlier line opened: CodeLanguage::states, line_tokens), so a long text can be read from any line. It has no dependency and builds for the browser. An app describes a language of its own with the same table, or changes one of lurq’s:
use lurq::code::{CodeLanguage, KeyRule, StringForm, token};
let ini = CodeLanguage::new("ini") .line_comments(&[";", "#"]) .strings(vec![StringForm::new("\"", "\"")]) .words(token::CONSTANT_LANGUAGE, &["true", "false"]) .keys(KeyRule::Equals) .sections(true);app.register_tokenizer("ini", ini);app.register_tokenizer("rust", CodeLanguage::rust().words(token::KEYWORD, &["yeet"]));A tokenizer of another crate is plugged in by an adapter that names its runs. The gallery does it with syntect (crates/gallery/src/syntect_code.rs), which lurq does not depend on: syntect’s scopes (keyword.control.rust, string.quoted.double, entity.name.function) mapped to lurq’s names, registered for Go, C and Java, and given to one block of the Code Block page in place of lurq’s Rust.
A tokenizer with state
Section titled “A tokenizer with state”A tokenizer may keep what it needs between calls: it is registered once (register_tokenizer takes the value, and keeps it), and a struct with a cache, a loaded grammar or a parser is as much a tokenizer as a function. Three things make one fast and correct, each a method of Tokenizer with a default, so a function stays one line:
use std::sync::{Arc, OnceLock};
use lurq::code::{CodeToken, LineState, Tokenizer, TokenizerHandle, token};
/// A tokenizer whose grammar loads after the app starts. Until it has, its code is plain.struct Lazy { grammar: Arc<OnceLock<Vec<String>>>,}
/// What a line of it starts in: inside a `"""` string or not.#[derive(Clone, PartialEq)]struct InString(bool);
impl Lazy { /// The tokens of one line, from the state it starts in; `state` is the next line's after. fn line(&self, line: &str, state: &mut InString) -> Vec<CodeToken> { let mut found = Vec::new(); if line.matches("\"\"\"").count() % 2 == 1 { state.0 = !state.0; } if state.0 || line.contains("\"\"\"") { found.push(CodeToken::new(0..line.len(), token::STRING)); } else if let Some(words) = self.grammar.get() { let mut at = 0; for word in line.split(' ') { if words.iter().any(|known| known == word) { found.push(CodeToken::new(at..at + word.len(), token::KEYWORD)); } at += word.len() + 1; } } found }}
impl Tokenizer for Lazy { fn tokens(&self, code: &str) -> Vec<CodeToken> { let mut state = InString(false); let mut at = 0; let mut found = Vec::new(); for line in code.split('\n') { found.extend(self.line(line, &mut state).into_iter().map(|token| { CodeToken::new(token.range.start + at..token.range.end + at, token.kind) })); at += line.len() + 1; } found }
/// Line by line: an edit is tokenized again from its line until a line starts as it did. fn tokens_from(&self, lines: &[&str], start: &LineState) -> Option<Vec<(Vec<CodeToken>, LineState)>> { let mut state = start.get::<InString>().cloned().unwrap_or(InString(false)); Some( lines .iter() .map(|line| (self.line(line, &mut state), LineState::new(state.clone()))) .collect(), ) }}
let grammar = Arc::new(OnceLock::new());let handle: TokenizerHandle = app.register_tokenizer("notes", Lazy { grammar: grammar.clone() });// Later, when the grammar has loaded: what showed "notes" plain is drawn again with its keywords.grammar.set(vec!["note".to_owned(), "due".to_owned()]).ok();handle.invalidate();- By line (
tokens_from): the tokens of a few lines from the state the first starts in, and the state each next one starts in. The state is aLineState, any value that isClone + PartialEq + Send + Sync: a small enum (lurq’s own scanner keeps itsScanState), or a parser’s stack (the gallery’s syntect keeps itsParseStateandScopeStack). lurq compares two of them, so a number would not hold a parser’s stack, and a value it cannot compare would let no edit stop early. lurq keeps the state each line starts in, for a code field’s text and for a mounted code block’s code (a Markdown fence streamed in): an edit is tokenized again from its first changed line until a line starts in the state it started in before, and the lines after are taken as they were. One character typed in ten thousand lines tokenizes a batch of 32 lines, and the tokens are those of the whole text tokenized again. A tokenizer that does not go line by line is asked for the whole text, and what it gave is kept by the code. - Stale (
TokenizerHandle):register_tokenizergives it back, andCodeTokenizer::handle()gives one before a tokenizer is registered (to hand to what loads its grammar).invalidate()forgets what the tokenizer gave and draws again whatever shows a language it serves, or has it as a block’s own: a grammar loaded later, a setting changed. - Edits (
tokens_in,edited,dropped): for an incremental parser such as tree-sitter, which keeps a tree for each text and is told how it changed. A code field is a buffer (BufferId); each change of its value is told to its tokenizer in order, before the tokens after it are asked, as aCodeEditin tree-sitter’sInputEditshape (start_byte,old_end_byte,new_end_byte, and the same asCodePointrows and byte columns), typed, deleted, pasted and undone alike. A change of a run of the same character (a secondatyped after ana) is told at the run’s end.tokens_in(buffer, code)asks the tokens of that buffer’s text, anddropped(buffer)says it is gone, once its field has left the tree and the focus has left it.
The gallery’s syntect example is a tokenizer with state: syntect’s parser goes line by line from where the line before left it, which is tokens_from (crates/gallery/src/syntect_code.rs).
The colors are the theme’s: a CodeScheme, a style (color, weight, leaning) for each name, one for the light appearance and one for the dark (Code). CodeScheme::lurq() is the theme’s unless told, in the palette’s roles, so code looks as the rest of the theme does in both appearances. A block styles a name over them with .token_style(name, |s| s.foreground(..).bold().italic()), or draws in a scheme of its own with .code_scheme(..).
A long block: a code block of more than 400 lines lays out and paints the lines in view and a chunk around them, whatever its length: in its own room where it has a greatest height, and in the window where it has none, as a long fence of a document has. Such a fence is selected on its own (select all takes its code whole) and is not one text with the document’s highlights. Ten thousand lines of Rust take what a screen of them takes: the frame paints ten quads and some 13 KB of text, where it painted 140 009 quads and all 600 KB before. See Code Block.
A code field colors its value by the same names, colors, weights and leaning, in its own type, again after every edit: TextInput::code_language("sql"), or .code_tokenizer(h). It is built on TextInput::tokens_with(f), tokens asked of each value the input holds (Source-backed input tokens).
A paragraph is one text, links included: it wraps and selects as one. Each link in it is a Tab stop in document order; a click and Enter follow it (Space does not), the pointer shows a pointer cursor, and an MCP client sees it as a link named by its words. on_link_select runs inside the input’s dispatch, so lurq::app::events::is_synthetic_input() tells a person’s press from an MCP client’s, and MarkdownLink::index() says which link it was.
on_link_select gets left clicks and Enter. To tell how a link was activated, use .on_link_activate(...): it gets the link and the MouseEvent that activated it, for a left click, a middle click, or Enter on the focused link. The event’s button is Left or Middle (Left for Enter), from_keyboard is set for Enter, and shift, ctrl, alt and meta are the modifiers held (meta is Cmd on macOS and the Windows key on Windows). Browser rules for a chat’s links, for example:
use lurq::app::events::MouseButton;
MarkdownProps::new(reply).on_link_activate(move |link, event| { let shortcut = if cfg!(target_os = "macos") { event.meta } else { event.ctrl }; if event.button == MouseButton::Middle || (shortcut && !event.shift) { tabs.open_in_background(link.destination()); } else if shortcut && event.shift { tabs.open_and_switch(link.destination()); } else { tabs.open_here(link.destination()); }})- A middle click is a press and a release of the middle button on the same link, like a left click: a press released off the link activates nothing, and neither does a press on one link released on another more than a few pixels away. Closer than that, the link under the release activates, as with a left click. The press starts no text selection, no drag of what the link is in and no middle-button autoscroll of the container around it, and lurq has no middle-click paste for it to start.
on_link_activateruns beforeon_link_select, which still gets the left clicks and Enter when both are set. Withon_link_activateset, an in-app link no longer navigates the router by itself. Without it, a middle click on a link does nothing.- It runs inside the input’s dispatch, like
on_link_select: an MCP client’slurq_interactclick with"button": "middle"or"modifiers": ["ctrl", "meta"]reaches it with those, andis_synthetic_input()istrue.
.link_presentation(...) decides how each link is shown. It is called once per link and render with the same MarkdownLink that on_link_select gets, so what a link shows always comes from the destination it opens:
use lurq::{ app::theme::{MarkdownFocusRing, MarkdownInlineStyle, MarkdownLinkState, MarkdownTextStyle}, components::{MarkdownLinkPresentation, MarkdownProps, MarkdownRun}, layout::text_style::TextUnderline, markdown::isolate_bidi,};
let words = MarkdownInlineStyle { text: MarkdownTextStyle { color: Some(accent), underline: Some(TextUnderline::new().color(muted).thickness(1.0)), ..Default::default() },};MarkdownProps::new(reply) .link_presentation(move |link| match kind_of(link.destination()) { // In the app: the link look, a tooltip naming the place. Kind::App(place) => MarkdownLinkPresentation::link() .style(words.clone()) .hovered(MarkdownLinkState::new().color(accent_hover).background(hover_fill).underline_color(accent_hover)) .focus_ring(Some(MarkdownFocusRing::new(2.0, focus).radius(3.0))) .tooltip(format!("{place} · opens in this tab")), // On the web: the host and an icon glyph after the words. Kind::Web(host) => MarkdownLinkPresentation::link() .style(words.clone()) .trailing([MarkdownRun::new(format!("\u{a0}{host}\u{a0}\u{e04d}"), host_style.clone())]) .hovered(MarkdownLinkState::new().trailing_color(secondary)) // A destination is text the reply's author wrote: isolate it so its // directional controls cannot reorder the sentence around it. .tooltip(format!("Opens {} in your browser", isolate_bidi(link.destination()))), // Anything else is not followed: the words as text, then the address. Kind::Other => MarkdownLinkPresentation::text() // A run is stripped of directional controls and isolated by lurq. .trailing([MarkdownRun::new(format!(" ({})", link.destination()), address_style.clone())]), }) .on_link_select(move |link| open(link.destination(), lurq::app::events::is_synthetic_input()))link()draws the words in the theme’slinkstyle, or the presentation’sstyle(...)over the text around them.text()draws them as the surrounding text: nothing to press or focus.trailing(...)runs follow the words in the same paragraph, so they wrap with it; each run’s style applies over the text around the link. After a link, the pointer takes them as part of the link. Like CSS::aftercontent they are presentation: copying a selection, and inspection tools (MCP, DevTools), leave them out, and a selection highlight skips them.- The words and trailing runs are drawn between invisible bidi marks, and a paragraph with a link drops every directional control (U+202A–U+202E, U+2066–U+2069) and directional mark (U+200E, U+200F, U+061C) from its text, so lurq’s marks are the only ones left: a right-to-left override in the words or anywhere in the paragraph cannot draw a host after them backwards, not even past Unicode bidi’s nesting limit. In a right-to-left paragraph (Hebrew or Arabic text) the paragraph still reads right to left around each link, and a link’s trailing runs still follow its words, left to right. At any width, a laid-out line puts a link’s own runs, or nothing, right after its words. A link stays on one line where it fits; its words are one line of text (a hard break in them is a space). A link whose words draw nothing (none, or only spaces, invisible characters and combining marks with no letter) is not presented: it is its words as text, with no runs and nothing to press. The marks are invisible, are not copied and are not part of the paragraph’s
text_content. Text you build yourself from a destination outside a run (a tooltip, say) needs the same care:lurq::markdown::isolate_bidistrips the controls and marks and wraps the text in an isolate;strip_bidi_controlsonly strips. - A link’s name (
MarkdownLink::text(), and its MCP name) is its words as drawn: inline HTML as its text, an image as its alt text, without directional controls. An email autolink (<team@example.com>) reaches the app asmailto:team@example.com. hovered(...)andfocused(...)(MarkdownLinkState) recolor the words, their underline and the trailing runs, and can fill behind the words, one rectangle per line with the link’sradius(...). Keyboard focus (focus-visible) also draws thefocus_ring(...)around each line of the words, outside them on all sides and over the text. The document’s own containers do not clip it; a code block, a table or the app’s containers do.tooltip(...)shows under the link after the pointer rests on it forThemeMarkdown::link_tooltip_delay, and at once while it has keyboard focus. It lets the pointer through.pointer_only()leaves a link to the pointer, for an app whose reading text is not part of its Tab order: the link is no Tab stop, a press on it leaves the focus where it was, so Enter never reaches it and it never shows its focused look, its ring or a tooltip from the keyboard. A click and a middle click follow it, and the pointer over it shows its hovered look and its tooltip, as on any link.- Unset looks are the theme’s:
ThemeMarkdown::link,link_hovered,link_focused,link_focus_ring,link_radius,link_tooltipandlink_tooltip_box. - Underlines (
TextStyle::underline,MarkdownTextStyle::underline: color, thickness and offset, each defaulting to the text color and the font’s metrics) are drawn under every line a span covers, and lines through text (strikethrough: color and thickness) the same way.~~struck~~text has one by default, fromThemeMarkdown::strikethrough. A plainTextdraws both too; see layout.
.list_view(...) lets the app draw a list block itself. It is called for every list with a MarkdownList and returns the element to draw, or None to draw the list as usual. MarkdownList::inlines and blocks draw content as the document does, links included; decide from items() before drawing with them, since drawing numbers the links.