Struct AppOptions 

pub struct AppOptions { /* private fields */ }

Configuration for AppOptions::start.

Defaults to environment detection without probing, Ctrl-C to quit, and base-tree UiEvent::Cancel to shut down. A cancel from inside a visible modal overlay dismisses that layer instead of quitting.

Implementations

impl AppOptions

pub fn new() -> Self

Creates the default application configuration.

Examples found in repository

examples/companies.rs (line 193)

async fn main() -> io::Result<()> {
	let mut app = AppOptions::new()
		.mouse()
		.probe(Duration::from_millis(150))
		.graphics_with(forced_from_args)
		.start(|env| build_ui(env.viewport, env.ctx))
		.await?;
	if app.caps().graphics != Graphics::Cells {
		for (index, provider) in PROVIDERS.iter().enumerate() {
			let png = tokio::fs::read(format!("{ASSET_DIR}/{}.png", provider.id)).await?;
			app.renderer_mut().register_image(
				u32::try_from(index + 1).expect("provider count fits image IDs"),
				png,
			)?;
		}
		app.ui_mut().invalidate(SCROLL_ID);
	}
	show_stats(&mut app, None);
	let mut chosen: Option<String> = None;
	while let Some(event) = app.next().await? {
		match event {
			AppEvent::Resized(viewport) => {
				app.ui_mut().set_height(SCROLL_ID, scroll_height(viewport));
			},
			AppEvent::Pressed(id) => chosen = Some(id.to_string()),
			_ => {},
		}
		show_stats(&mut app, chosen.as_deref());
	}
	Ok(())
}

examples/tml.rs (line 49)

async fn main() -> io::Result<()> {
	let path = std::env::args()
		.nth(1)
		.unwrap_or_else(|| "example.tml".into());
	let source = std::fs::read_to_string(&path)?;

	let mut ctx = None;
	let mut app = AppOptions::new()
		.quit([Key::Ctrl('c'), Key::Char('q'), Key::Esc])
		.start(|env| {
			let ui = build(&source, env.viewport.width, &env.ctx);
			ctx = Some(env.ctx);
			ui
		})
		.await?;
	let ctx = ctx.expect("start ran the builder");

	let handle = app.handle();
	tokio::spawn(async move {
		let mut seen = modified(path.as_ref());
		loop {
			tokio::time::sleep(Duration::from_millis(150)).await;
			let stamp = modified(path.as_ref());
			if stamp == seen {
				continue;
			}
			seen = stamp;
			let Ok(source) = std::fs::read_to_string(&path) else {
				continue;
			};
			let ctx = ctx.clone();
			handle.update(move |ui| *ui = build(&source, ui.frame().size().width, &ctx));
		}
	});

	while app.next().await?.is_some() {}
	Ok(())
}

examples/gallery/main.rs (line 113)

async fn main() -> io::Result<()> {
	let mut app = AppOptions::new()
		.mouse()
		.quit([Key::Ctrl('c'), Key::Ctrl('q')])
		.start(|env| build_ui(env.viewport, env.ctx))
		.await?;
	// The picker tab opens with the first model's details, like the chat
	// overlay does.
	picker::show_detail_on(app.ui_mut(), Some(0));

	let mut synced = String::new();
	let mut lab = anim::Lab::new();
	let mut layers = Layers::default();
	let mut next_step = tokio::time::Instant::now() + anim::AUTOPLAY_STEP;

	loop {
		let event = tokio::select! {
			event = app.next() => match event? {
				Some(event) => event,
				None => break,
			},
			() = tokio::time::sleep_until(next_step) => {
				if lab.autoplay && active_tab(app.ui()) == "Anim" {
					lab.advance(app.ui_mut());
				}
				next_step += anim::AUTOPLAY_STEP;
				continue;
			},
		};
		match event {
			AppEvent::Resized(viewport) => {
				for pane in render::PANE_IDS {
					app.ui_mut().set_height(pane, render::pane_height(viewport));
				}
			},
			AppEvent::Key(key) => match active_tab(app.ui()).as_str() {
				"Anim" => lab.handle_key(key, app.ui_mut()),
				"Overlay" => match key {
					Key::Ctrl('k') if layers.picker.is_none() => {
						layers.picker = Some(overlay::show_picker(app.ui_mut()));
					},
					Key::Ctrl('g') => match layers.help.take() {
						Some(id) => {
							app.ui_mut().close_overlay(id);
						},
						None => layers.help = Some(overlay::show_help(app.ui_mut())),
					},
					_ => {},
				},
				_ => {},
			},
			// The Overlay tab's modal select committed a model.
			AppEvent::Changed { id, value } if id == "model" => {
				if let Some(overlay) = layers.picker.take() {
					let label = overlay::MODELS
						.iter()
						.find(|(short, ..)| *short == value)
						.map_or(value.as_str(), |(_, label, _)| label);
					app.ui_mut().set_text("status", format!("model: {label}"));
					app.ui_mut().close_overlay(overlay);
				}
			},
			// The Picker tab's select moved: mirror the chat picker's
			// facts-and-chips detail line.
			AppEvent::Highlighted { id, value } if id == "models" => {
				picker::show_detail_on(app.ui_mut(), value.as_str().parse().ok());
			},
			AppEvent::Filtered { id, value, .. } if id == "models" => {
				let model = value.and_then(|value| value.as_str().parse().ok());
				picker::show_detail_on(app.ui_mut(), model);
			},
			AppEvent::OverlayClosed(id) => {
				if layers.picker == Some(id) {
					layers.picker = None;
				}
				if layers.help == Some(id) {
					layers.help = None;
				}
			},
			_ => {},
		}
		render::sync_preview(app.ui_mut(), &mut synced);
		// Reserve the Overlay tab's chords only while it is showing, so the
		// focused composer can't spend Ctrl+K on kill-line — and the Live
		// tab's editor keeps it.
		let chords: &[Key] = if active_tab(app.ui()) == "Overlay" {
			&[Key::Ctrl('k'), Key::Ctrl('g')]
		} else {
			&[]
		};
		app.set_hotkeys(chords.iter().copied());
	}
	Ok(())
}

pub const fn probe(self, timeout: Duration) -> Self

Runs the startup capability probe with this timeout.

Examples found in repository

examples/companies.rs (line 195)

async fn main() -> io::Result<()> {
	let mut app = AppOptions::new()
		.mouse()
		.probe(Duration::from_millis(150))
		.graphics_with(forced_from_args)
		.start(|env| build_ui(env.viewport, env.ctx))
		.await?;
	if app.caps().graphics != Graphics::Cells {
		for (index, provider) in PROVIDERS.iter().enumerate() {
			let png = tokio::fs::read(format!("{ASSET_DIR}/{}.png", provider.id)).await?;
			app.renderer_mut().register_image(
				u32::try_from(index + 1).expect("provider count fits image IDs"),
				png,
			)?;
		}
		app.ui_mut().invalidate(SCROLL_ID);
	}
	show_stats(&mut app, None);
	let mut chosen: Option<String> = None;
	while let Some(event) = app.next().await? {
		match event {
			AppEvent::Resized(viewport) => {
				app.ui_mut().set_height(SCROLL_ID, scroll_height(viewport));
			},
			AppEvent::Pressed(id) => chosen = Some(id.to_string()),
			_ => {},
		}
		show_stats(&mut app, chosen.as_deref());
	}
	Ok(())
}

pub fn graphics_with( self, forced: impl FnOnce(&TerminalCaps) -> Option<Graphics> + Send + 'static, ) -> Self

Resolves an optional forced graphics tier after capability detection.

Examples found in repository

examples/companies.rs (line 196)

async fn main() -> io::Result<()> {
	let mut app = AppOptions::new()
		.mouse()
		.probe(Duration::from_millis(150))
		.graphics_with(forced_from_args)
		.start(|env| build_ui(env.viewport, env.ctx))
		.await?;
	if app.caps().graphics != Graphics::Cells {
		for (index, provider) in PROVIDERS.iter().enumerate() {
			let png = tokio::fs::read(format!("{ASSET_DIR}/{}.png", provider.id)).await?;
			app.renderer_mut().register_image(
				u32::try_from(index + 1).expect("provider count fits image IDs"),
				png,
			)?;
		}
		app.ui_mut().invalidate(SCROLL_ID);
	}
	show_stats(&mut app, None);
	let mut chosen: Option<String> = None;
	while let Some(event) = app.next().await? {
		match event {
			AppEvent::Resized(viewport) => {
				app.ui_mut().set_height(SCROLL_ID, scroll_height(viewport));
			},
			AppEvent::Pressed(id) => chosen = Some(id.to_string()),
			_ => {},
		}
		show_stats(&mut app, chosen.as_deref());
	}
	Ok(())
}

pub const fn cursor_style(self, style: CursorStyle) -> Self

Uses style while the application owns the terminal.

pub const fn mouse(self) -> Self

Enables inline mouse reporting (click, drag, motion, wheel) for the whole session.

Off by default: an inline app leaves the mouse to the terminal so native text selection and scrollback keep working, matching the coding agent. Opt in for pointer-driven screens.

Examples found in repository

examples/companies.rs (line 194)

async fn main() -> io::Result<()> {
	let mut app = AppOptions::new()
		.mouse()
		.probe(Duration::from_millis(150))
		.graphics_with(forced_from_args)
		.start(|env| build_ui(env.viewport, env.ctx))
		.await?;
	if app.caps().graphics != Graphics::Cells {
		for (index, provider) in PROVIDERS.iter().enumerate() {
			let png = tokio::fs::read(format!("{ASSET_DIR}/{}.png", provider.id)).await?;
			app.renderer_mut().register_image(
				u32::try_from(index + 1).expect("provider count fits image IDs"),
				png,
			)?;
		}
		app.ui_mut().invalidate(SCROLL_ID);
	}
	show_stats(&mut app, None);
	let mut chosen: Option<String> = None;
	while let Some(event) = app.next().await? {
		match event {
			AppEvent::Resized(viewport) => {
				app.ui_mut().set_height(SCROLL_ID, scroll_height(viewport));
			},
			AppEvent::Pressed(id) => chosen = Some(id.to_string()),
			_ => {},
		}
		show_stats(&mut app, chosen.as_deref());
	}
	Ok(())
}

examples/gallery/main.rs (line 114)

async fn main() -> io::Result<()> {
	let mut app = AppOptions::new()
		.mouse()
		.quit([Key::Ctrl('c'), Key::Ctrl('q')])
		.start(|env| build_ui(env.viewport, env.ctx))
		.await?;
	// The picker tab opens with the first model's details, like the chat
	// overlay does.
	picker::show_detail_on(app.ui_mut(), Some(0));

	let mut synced = String::new();
	let mut lab = anim::Lab::new();
	let mut layers = Layers::default();
	let mut next_step = tokio::time::Instant::now() + anim::AUTOPLAY_STEP;

	loop {
		let event = tokio::select! {
			event = app.next() => match event? {
				Some(event) => event,
				None => break,
			},
			() = tokio::time::sleep_until(next_step) => {
				if lab.autoplay && active_tab(app.ui()) == "Anim" {
					lab.advance(app.ui_mut());
				}
				next_step += anim::AUTOPLAY_STEP;
				continue;
			},
		};
		match event {
			AppEvent::Resized(viewport) => {
				for pane in render::PANE_IDS {
					app.ui_mut().set_height(pane, render::pane_height(viewport));
				}
			},
			AppEvent::Key(key) => match active_tab(app.ui()).as_str() {
				"Anim" => lab.handle_key(key, app.ui_mut()),
				"Overlay" => match key {
					Key::Ctrl('k') if layers.picker.is_none() => {
						layers.picker = Some(overlay::show_picker(app.ui_mut()));
					},
					Key::Ctrl('g') => match layers.help.take() {
						Some(id) => {
							app.ui_mut().close_overlay(id);
						},
						None => layers.help = Some(overlay::show_help(app.ui_mut())),
					},
					_ => {},
				},
				_ => {},
			},
			// The Overlay tab's modal select committed a model.
			AppEvent::Changed { id, value } if id == "model" => {
				if let Some(overlay) = layers.picker.take() {
					let label = overlay::MODELS
						.iter()
						.find(|(short, ..)| *short == value)
						.map_or(value.as_str(), |(_, label, _)| label);
					app.ui_mut().set_text("status", format!("model: {label}"));
					app.ui_mut().close_overlay(overlay);
				}
			},
			// The Picker tab's select moved: mirror the chat picker's
			// facts-and-chips detail line.
			AppEvent::Highlighted { id, value } if id == "models" => {
				picker::show_detail_on(app.ui_mut(), value.as_str().parse().ok());
			},
			AppEvent::Filtered { id, value, .. } if id == "models" => {
				let model = value.and_then(|value| value.as_str().parse().ok());
				picker::show_detail_on(app.ui_mut(), model);
			},
			AppEvent::OverlayClosed(id) => {
				if layers.picker == Some(id) {
					layers.picker = None;
				}
				if layers.help == Some(id) {
					layers.help = None;
				}
			},
			_ => {},
		}
		render::sync_preview(app.ui_mut(), &mut synced);
		// Reserve the Overlay tab's chords only while it is showing, so the
		// focused composer can't spend Ctrl+K on kill-line — and the Live
		// tab's editor keeps it.
		let chords: &[Key] = if active_tab(app.ui()) == "Overlay" {
			&[Key::Ctrl('k'), Key::Ctrl('g')]
		} else {
			&[]
		};
		app.set_hotkeys(chords.iter().copied());
	}
	Ok(())
}

pub fn quit(self, chords: impl IntoIterator<Item = Key>) -> Self

Replaces the quit chords checked before input routing.

Examples found in repository

examples/tml.rs (line 50)

async fn main() -> io::Result<()> {
	let path = std::env::args()
		.nth(1)
		.unwrap_or_else(|| "example.tml".into());
	let source = std::fs::read_to_string(&path)?;

	let mut ctx = None;
	let mut app = AppOptions::new()
		.quit([Key::Ctrl('c'), Key::Char('q'), Key::Esc])
		.start(|env| {
			let ui = build(&source, env.viewport.width, &env.ctx);
			ctx = Some(env.ctx);
			ui
		})
		.await?;
	let ctx = ctx.expect("start ran the builder");

	let handle = app.handle();
	tokio::spawn(async move {
		let mut seen = modified(path.as_ref());
		loop {
			tokio::time::sleep(Duration::from_millis(150)).await;
			let stamp = modified(path.as_ref());
			if stamp == seen {
				continue;
			}
			seen = stamp;
			let Ok(source) = std::fs::read_to_string(&path) else {
				continue;
			};
			let ctx = ctx.clone();
			handle.update(move |ui| *ui = build(&source, ui.frame().size().width, &ctx));
		}
	});

	while app.next().await?.is_some() {}
	Ok(())
}

examples/gallery/main.rs (line 115)

async fn main() -> io::Result<()> {
	let mut app = AppOptions::new()
		.mouse()
		.quit([Key::Ctrl('c'), Key::Ctrl('q')])
		.start(|env| build_ui(env.viewport, env.ctx))
		.await?;
	// The picker tab opens with the first model's details, like the chat
	// overlay does.
	picker::show_detail_on(app.ui_mut(), Some(0));

	let mut synced = String::new();
	let mut lab = anim::Lab::new();
	let mut layers = Layers::default();
	let mut next_step = tokio::time::Instant::now() + anim::AUTOPLAY_STEP;

	loop {
		let event = tokio::select! {
			event = app.next() => match event? {
				Some(event) => event,
				None => break,
			},
			() = tokio::time::sleep_until(next_step) => {
				if lab.autoplay && active_tab(app.ui()) == "Anim" {
					lab.advance(app.ui_mut());
				}
				next_step += anim::AUTOPLAY_STEP;
				continue;
			},
		};
		match event {
			AppEvent::Resized(viewport) => {
				for pane in render::PANE_IDS {
					app.ui_mut().set_height(pane, render::pane_height(viewport));
				}
			},
			AppEvent::Key(key) => match active_tab(app.ui()).as_str() {
				"Anim" => lab.handle_key(key, app.ui_mut()),
				"Overlay" => match key {
					Key::Ctrl('k') if layers.picker.is_none() => {
						layers.picker = Some(overlay::show_picker(app.ui_mut()));
					},
					Key::Ctrl('g') => match layers.help.take() {
						Some(id) => {
							app.ui_mut().close_overlay(id);
						},
						None => layers.help = Some(overlay::show_help(app.ui_mut())),
					},
					_ => {},
				},
				_ => {},
			},
			// The Overlay tab's modal select committed a model.
			AppEvent::Changed { id, value } if id == "model" => {
				if let Some(overlay) = layers.picker.take() {
					let label = overlay::MODELS
						.iter()
						.find(|(short, ..)| *short == value)
						.map_or(value.as_str(), |(_, label, _)| label);
					app.ui_mut().set_text("status", format!("model: {label}"));
					app.ui_mut().close_overlay(overlay);
				}
			},
			// The Picker tab's select moved: mirror the chat picker's
			// facts-and-chips detail line.
			AppEvent::Highlighted { id, value } if id == "models" => {
				picker::show_detail_on(app.ui_mut(), value.as_str().parse().ok());
			},
			AppEvent::Filtered { id, value, .. } if id == "models" => {
				let model = value.and_then(|value| value.as_str().parse().ok());
				picker::show_detail_on(app.ui_mut(), model);
			},
			AppEvent::OverlayClosed(id) => {
				if layers.picker == Some(id) {
					layers.picker = None;
				}
				if layers.help == Some(id) {
					layers.help = None;
				}
			},
			_ => {},
		}
		render::sync_preview(app.ui_mut(), &mut synced);
		// Reserve the Overlay tab's chords only while it is showing, so the
		// focused composer can't spend Ctrl+K on kill-line — and the Live
		// tab's editor keeps it.
		let chords: &[Key] = if active_tab(app.ui()) == "Overlay" {
			&[Key::Ctrl('k'), Key::Ctrl('g')]
		} else {
			&[]
		};
		app.set_hotkeys(chords.iter().copied());
	}
	Ok(())
}

pub fn hotkeys(self, chords: impl IntoIterator<Item = Key>) -> Self

Reserves chords for the host, checked after the quit chords and before widget routing, and surfaced as AppEvent::Key.

Use this for scene-level shortcuts that must win over a focused widget’s own binding — Ctrl+K opening a switcher while a text input would otherwise kill to end of line. Chords stay reserved until App::set_hotkeys replaces them, so scope them to the screen that needs them rather than reserving them globally.

pub const fn hold_alt(self) -> Self

Starts with the alternate screen held: the very first frame paints there and the inline transcript stays untouched underneath until App::hold_alt releases it. Fullscreen opening scenes — a welcome screen, a picker-first flow — use this so the main buffer never flashes frame one. A Ui whose initial overlay stack is visible holds automatically without this option.

pub const fn keep_on_cancel(self) -> Self

Keeps running when the base tree yields UiEvent::Cancel.

A cancel from inside a visible modal overlay is unaffected: it always dismisses that layer and surfaces AppEvent::OverlayClosed.

pub async fn start(self, build: impl FnOnce(AppEnv) -> Ui + Send) -> Result<App>

Negotiates, enters the terminal, builds the Ui, paints the first frame, and returns the running host.

Errors

Propagates terminal, input, capability, and renderer failures.

Examples found in repository

examples/companies.rs (line 197)

async fn main() -> io::Result<()> {
	let mut app = AppOptions::new()
		.mouse()
		.probe(Duration::from_millis(150))
		.graphics_with(forced_from_args)
		.start(|env| build_ui(env.viewport, env.ctx))
		.await?;
	if app.caps().graphics != Graphics::Cells {
		for (index, provider) in PROVIDERS.iter().enumerate() {
			let png = tokio::fs::read(format!("{ASSET_DIR}/{}.png", provider.id)).await?;
			app.renderer_mut().register_image(
				u32::try_from(index + 1).expect("provider count fits image IDs"),
				png,
			)?;
		}
		app.ui_mut().invalidate(SCROLL_ID);
	}
	show_stats(&mut app, None);
	let mut chosen: Option<String> = None;
	while let Some(event) = app.next().await? {
		match event {
			AppEvent::Resized(viewport) => {
				app.ui_mut().set_height(SCROLL_ID, scroll_height(viewport));
			},
			AppEvent::Pressed(id) => chosen = Some(id.to_string()),
			_ => {},
		}
		show_stats(&mut app, chosen.as_deref());
	}
	Ok(())
}

examples/tml.rs (lines 51-55)

async fn main() -> io::Result<()> {
	let path = std::env::args()
		.nth(1)
		.unwrap_or_else(|| "example.tml".into());
	let source = std::fs::read_to_string(&path)?;

	let mut ctx = None;
	let mut app = AppOptions::new()
		.quit([Key::Ctrl('c'), Key::Char('q'), Key::Esc])
		.start(|env| {
			let ui = build(&source, env.viewport.width, &env.ctx);
			ctx = Some(env.ctx);
			ui
		})
		.await?;
	let ctx = ctx.expect("start ran the builder");

	let handle = app.handle();
	tokio::spawn(async move {
		let mut seen = modified(path.as_ref());
		loop {
			tokio::time::sleep(Duration::from_millis(150)).await;
			let stamp = modified(path.as_ref());
			if stamp == seen {
				continue;
			}
			seen = stamp;
			let Ok(source) = std::fs::read_to_string(&path) else {
				continue;
			};
			let ctx = ctx.clone();
			handle.update(move |ui| *ui = build(&source, ui.frame().size().width, &ctx));
		}
	});

	while app.next().await?.is_some() {}
	Ok(())
}

examples/gallery/main.rs (line 116)

async fn main() -> io::Result<()> {
	let mut app = AppOptions::new()
		.mouse()
		.quit([Key::Ctrl('c'), Key::Ctrl('q')])
		.start(|env| build_ui(env.viewport, env.ctx))
		.await?;
	// The picker tab opens with the first model's details, like the chat
	// overlay does.
	picker::show_detail_on(app.ui_mut(), Some(0));

	let mut synced = String::new();
	let mut lab = anim::Lab::new();
	let mut layers = Layers::default();
	let mut next_step = tokio::time::Instant::now() + anim::AUTOPLAY_STEP;

	loop {
		let event = tokio::select! {
			event = app.next() => match event? {
				Some(event) => event,
				None => break,
			},
			() = tokio::time::sleep_until(next_step) => {
				if lab.autoplay && active_tab(app.ui()) == "Anim" {
					lab.advance(app.ui_mut());
				}
				next_step += anim::AUTOPLAY_STEP;
				continue;
			},
		};
		match event {
			AppEvent::Resized(viewport) => {
				for pane in render::PANE_IDS {
					app.ui_mut().set_height(pane, render::pane_height(viewport));
				}
			},
			AppEvent::Key(key) => match active_tab(app.ui()).as_str() {
				"Anim" => lab.handle_key(key, app.ui_mut()),
				"Overlay" => match key {
					Key::Ctrl('k') if layers.picker.is_none() => {
						layers.picker = Some(overlay::show_picker(app.ui_mut()));
					},
					Key::Ctrl('g') => match layers.help.take() {
						Some(id) => {
							app.ui_mut().close_overlay(id);
						},
						None => layers.help = Some(overlay::show_help(app.ui_mut())),
					},
					_ => {},
				},
				_ => {},
			},
			// The Overlay tab's modal select committed a model.
			AppEvent::Changed { id, value } if id == "model" => {
				if let Some(overlay) = layers.picker.take() {
					let label = overlay::MODELS
						.iter()
						.find(|(short, ..)| *short == value)
						.map_or(value.as_str(), |(_, label, _)| label);
					app.ui_mut().set_text("status", format!("model: {label}"));
					app.ui_mut().close_overlay(overlay);
				}
			},
			// The Picker tab's select moved: mirror the chat picker's
			// facts-and-chips detail line.
			AppEvent::Highlighted { id, value } if id == "models" => {
				picker::show_detail_on(app.ui_mut(), value.as_str().parse().ok());
			},
			AppEvent::Filtered { id, value, .. } if id == "models" => {
				let model = value.and_then(|value| value.as_str().parse().ok());
				picker::show_detail_on(app.ui_mut(), model);
			},
			AppEvent::OverlayClosed(id) => {
				if layers.picker == Some(id) {
					layers.picker = None;
				}
				if layers.help == Some(id) {
					layers.help = None;
				}
			},
			_ => {},
		}
		render::sync_preview(app.ui_mut(), &mut synced);
		// Reserve the Overlay tab's chords only while it is showing, so the
		// focused composer can't spend Ctrl+K on kill-line — and the Live
		// tab's editor keeps it.
		let chords: &[Key] = if active_tab(app.ui()) == "Overlay" {
			&[Key::Ctrl('k'), Key::Ctrl('g')]
		} else {
			&[]
		};
		app.set_hotkeys(chords.iter().copied());
	}
	Ok(())
}

Trait Implementations

impl Default for AppOptions

fn default() -> Self

Returns the “default value” for a type.