Struct OverlayOptions 

#[non_exhaustive]
pub struct OverlayOptions {

    pub width: Option<Dim>,
    pub min_width: Option<u16>,
    pub max_height: Option<Dim>,
    pub anchor: OverlayAnchor,
    pub offset_x: i16,
    pub offset_y: i16,
    pub row: Option<Dim>,
    pub col: Option<Dim>,
    pub margin: OverlayMargin,
    pub z: i16,
    pub min_viewport: Size,
    pub modal: bool,
    pub fill_height: bool,
}

Declarative sizing, placement, and visibility options for an overlay.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

width: Option<Dim>

Requested width, resolved against the full viewport width.

min_width: Option<u16>

Minimum width applied before fitting the overlay to its margins.

max_height: Option<Dim>

Maximum height, resolved against the full viewport height.

anchor: OverlayAnchor

Viewport position used when no explicit row or column is supplied.

offset_x: i16

Horizontal displacement from the resolved position.

offset_y: i16

Vertical displacement from the resolved position.

row: Option<Dim>

Explicit absolute or percentage row position.

col: Option<Dim>

Explicit absolute or percentage column position.

margin: OverlayMargin

Insets from viewport edges.

z: i16

Stacking height: higher layers composite above lower ones; ties stack by creation order.

min_viewport: Size

Smallest viewport in which the overlay is visible.

modal: bool

Whether the layer captures the keyboard while visible (the default).

A non-modal layer — a sidebar, a status rail — leaves keys and paste with the base tree unless explicitly focused through crate::Ui::focus_overlay, and never triggers the crate::App alternate-screen hold: the document keeps committing to native scrollback beneath it while the layer rides the live viewport.

fill_height: bool

Stretches a retained overlay tree to the full available viewport height (after margin and max_height) instead of its content height, so grow/valign fill the band like a full-height rail.

Raw-frame Layer hosts control their frame height directly; the band there always follows the frame.

Implementations

impl OverlayOptions

pub const fn width(self, width: Dim) -> Self

Sets the requested width.

Examples found in repository

examples/chat/sidebar.rs (line 59)

	pub fn new(model: &str, ctx: &UiContext) -> Self {
		let options = OverlayOptions::default()
			.anchor(OverlayAnchor::Right)
			.width(Dim::Cells(WIDTH))
			.non_modal()
			.min_viewport(MIN_VIEWPORT);
		let mut ui = build(model, ctx);
		// The rail starts without the keyboard: no focus chrome or frame
		// cursor until `toggle` or a click hands it over.
		ui.blur();
		Self { ui, options, open: true, focused: false, elapsed_seconds: 0, height: 0 }
	}

examples/chat/picker.rs (line 260)

	pub fn open(current: usize, ctx: &UiContext) -> Self {
		let options = OverlayOptions::default()
			.anchor(OverlayAnchor::Bottom)
			.width(Dim::Pct(100))
			.z(10);
		let mode = Mode::Models;
		let tier = PerfTier::Full;
		let ui = build(mode, tier, current, "", 5, 100, ctx);
		let mut picker = Self {
			ui,
			mode,
			tier,
			current,
			ctx: ctx.clone(),
			options,
			query: Str::default(),
			rows: 5,
		};
		picker.show_detail(Some(current));
		picker
	}

examples/gallery/overlay.rs (line 51)

pub(crate) fn show_picker(ui: &mut Ui) -> OverlayId {
	ui.show_overlay(
		dom! {
			<box border=round title="Switch Model">
				<col gap=1>
					<text dim>{"Session-only switch — role models stay unchanged"}</text>
					<select id=model>
						for (value, label, stats) in MODELS {
							<option value={value} desc={stats}>{label}</option>
						}
					</select>
				</col>
			</box>
		},
		OverlayOptions::default()
			.anchor(OverlayAnchor::Center)
			.width(Dim::Pct(70))
			.min_width(48)
			.max_height(Dim::Pct(60))
			.min_viewport(Size::new(40, 8)),
	)
}

/// Opens the keybinding help layer.
pub(crate) fn show_help(ui: &mut Ui) -> OverlayId {
	ui.show_overlay(
		dom! {
			<box border=round title="Help">
				<col>
					<text>{"Ctrl+K  switch model"}</text>
					<text>{"Ctrl+G  toggle this help"}</text>
					<text>{"Esc     close top layer"}</text>
					<text>{"Ctrl+C  quit"}</text>
				</col>
			</box>
		},
		OverlayOptions::default()
			.anchor(OverlayAnchor::BottomRight)
			.width(Dim::Cells(30))
			.margin(OverlayMargin::uniform(1)),
	)
}

examples/chat/commands.rs (line 121)

	pub fn layer(&mut self, viewport: Size) -> Layer<'_> {
		let width = (viewport.width * 3 / 5).max(48).min(viewport.width);
		let rows = (viewport.height / 2).saturating_sub(FRAME_ROWS).max(5);
		if rows != self.rows {
			self.rows = rows;
			// One query row plus the windowed list.
			self
				.ui
				.set_prop("commands", Prop::H, rows.saturating_add(1));
		}
		if self.ui.frame().size().width != width {
			self.ui = build(&self.query, self.rows, width, &self.ctx);
		}
		self.options = self.options.width(Dim::Cells(width));
		Layer { frame: self.ui.frame(), options: &self.options, active: true }
	}

pub const fn min_width(self, min_width: u16) -> Self

Sets the minimum width in cells.

Examples found in repository

examples/gallery/overlay.rs (line 52)

pub(crate) fn show_picker(ui: &mut Ui) -> OverlayId {
	ui.show_overlay(
		dom! {
			<box border=round title="Switch Model">
				<col gap=1>
					<text dim>{"Session-only switch — role models stay unchanged"}</text>
					<select id=model>
						for (value, label, stats) in MODELS {
							<option value={value} desc={stats}>{label}</option>
						}
					</select>
				</col>
			</box>
		},
		OverlayOptions::default()
			.anchor(OverlayAnchor::Center)
			.width(Dim::Pct(70))
			.min_width(48)
			.max_height(Dim::Pct(60))
			.min_viewport(Size::new(40, 8)),
	)
}

pub const fn max_height(self, max_height: Dim) -> Self

Sets the maximum height.

Examples found in repository

examples/gallery/overlay.rs (line 53)

pub(crate) fn show_picker(ui: &mut Ui) -> OverlayId {
	ui.show_overlay(
		dom! {
			<box border=round title="Switch Model">
				<col gap=1>
					<text dim>{"Session-only switch — role models stay unchanged"}</text>
					<select id=model>
						for (value, label, stats) in MODELS {
							<option value={value} desc={stats}>{label}</option>
						}
					</select>
				</col>
			</box>
		},
		OverlayOptions::default()
			.anchor(OverlayAnchor::Center)
			.width(Dim::Pct(70))
			.min_width(48)
			.max_height(Dim::Pct(60))
			.min_viewport(Size::new(40, 8)),
	)
}

pub const fn z(self, z: i16) -> Self

Sets the stacking height.

Examples found in repository

examples/chat/commands.rs (line 77)

	pub fn open(ctx: &UiContext) -> Self {
		let options = OverlayOptions::default()
			.anchor(OverlayAnchor::Top)
			.offset_y(1)
			.z(10);
		Self { ui: build("", 8, 100, ctx), ctx: ctx.clone(), options, query: Str::default(), rows: 8 }
	}

examples/chat/picker.rs (line 261)

	pub fn open(current: usize, ctx: &UiContext) -> Self {
		let options = OverlayOptions::default()
			.anchor(OverlayAnchor::Bottom)
			.width(Dim::Pct(100))
			.z(10);
		let mode = Mode::Models;
		let tier = PerfTier::Full;
		let ui = build(mode, tier, current, "", 5, 100, ctx);
		let mut picker = Self {
			ui,
			mode,
			tier,
			current,
			ctx: ctx.clone(),
			options,
			query: Str::default(),
			rows: 5,
		};
		picker.show_detail(Some(current));
		picker
	}

pub const fn anchor(self, anchor: OverlayAnchor) -> Self

Sets the fallback anchor position.

Examples found in repository

examples/chat/commands.rs (line 75)

	pub fn open(ctx: &UiContext) -> Self {
		let options = OverlayOptions::default()
			.anchor(OverlayAnchor::Top)
			.offset_y(1)
			.z(10);
		Self { ui: build("", 8, 100, ctx), ctx: ctx.clone(), options, query: Str::default(), rows: 8 }
	}

examples/chat/sidebar.rs (line 58)

	pub fn new(model: &str, ctx: &UiContext) -> Self {
		let options = OverlayOptions::default()
			.anchor(OverlayAnchor::Right)
			.width(Dim::Cells(WIDTH))
			.non_modal()
			.min_viewport(MIN_VIEWPORT);
		let mut ui = build(model, ctx);
		// The rail starts without the keyboard: no focus chrome or frame
		// cursor until `toggle` or a click hands it over.
		ui.blur();
		Self { ui, options, open: true, focused: false, elapsed_seconds: 0, height: 0 }
	}

examples/chat/picker.rs (line 259)

	pub fn open(current: usize, ctx: &UiContext) -> Self {
		let options = OverlayOptions::default()
			.anchor(OverlayAnchor::Bottom)
			.width(Dim::Pct(100))
			.z(10);
		let mode = Mode::Models;
		let tier = PerfTier::Full;
		let ui = build(mode, tier, current, "", 5, 100, ctx);
		let mut picker = Self {
			ui,
			mode,
			tier,
			current,
			ctx: ctx.clone(),
			options,
			query: Str::default(),
			rows: 5,
		};
		picker.show_detail(Some(current));
		picker
	}

examples/gallery/overlay.rs (line 50)

pub(crate) fn show_picker(ui: &mut Ui) -> OverlayId {
	ui.show_overlay(
		dom! {
			<box border=round title="Switch Model">
				<col gap=1>
					<text dim>{"Session-only switch — role models stay unchanged"}</text>
					<select id=model>
						for (value, label, stats) in MODELS {
							<option value={value} desc={stats}>{label}</option>
						}
					</select>
				</col>
			</box>
		},
		OverlayOptions::default()
			.anchor(OverlayAnchor::Center)
			.width(Dim::Pct(70))
			.min_width(48)
			.max_height(Dim::Pct(60))
			.min_viewport(Size::new(40, 8)),
	)
}

/// Opens the keybinding help layer.
pub(crate) fn show_help(ui: &mut Ui) -> OverlayId {
	ui.show_overlay(
		dom! {
			<box border=round title="Help">
				<col>
					<text>{"Ctrl+K  switch model"}</text>
					<text>{"Ctrl+G  toggle this help"}</text>
					<text>{"Esc     close top layer"}</text>
					<text>{"Ctrl+C  quit"}</text>
				</col>
			</box>
		},
		OverlayOptions::default()
			.anchor(OverlayAnchor::BottomRight)
			.width(Dim::Cells(30))
			.margin(OverlayMargin::uniform(1)),
	)
}

pub const fn offset_x(self, offset_x: i16) -> Self

Sets the horizontal offset in cells.

pub const fn offset_y(self, offset_y: i16) -> Self

Sets the vertical offset in cells.

Examples found in repository

examples/chat/commands.rs (line 76)

	pub fn open(ctx: &UiContext) -> Self {
		let options = OverlayOptions::default()
			.anchor(OverlayAnchor::Top)
			.offset_y(1)
			.z(10);
		Self { ui: build("", 8, 100, ctx), ctx: ctx.clone(), options, query: Str::default(), rows: 8 }
	}

pub const fn row(self, row: Dim) -> Self

Sets an explicit absolute or percentage row.

pub const fn col(self, col: Dim) -> Self

Sets an explicit absolute or percentage column.

pub const fn margin(self, margin: OverlayMargin) -> Self

Sets the viewport-edge insets.

Examples found in repository

examples/gallery/overlay.rs (line 74)

pub(crate) fn show_help(ui: &mut Ui) -> OverlayId {
	ui.show_overlay(
		dom! {
			<box border=round title="Help">
				<col>
					<text>{"Ctrl+K  switch model"}</text>
					<text>{"Ctrl+G  toggle this help"}</text>
					<text>{"Esc     close top layer"}</text>
					<text>{"Ctrl+C  quit"}</text>
				</col>
			</box>
		},
		OverlayOptions::default()
			.anchor(OverlayAnchor::BottomRight)
			.width(Dim::Cells(30))
			.margin(OverlayMargin::uniform(1)),
	)
}

pub const fn min_viewport(self, min_viewport: Size) -> Self

Sets the minimum viewport required for visibility.

Examples found in repository

examples/chat/sidebar.rs (line 61)

	pub fn new(model: &str, ctx: &UiContext) -> Self {
		let options = OverlayOptions::default()
			.anchor(OverlayAnchor::Right)
			.width(Dim::Cells(WIDTH))
			.non_modal()
			.min_viewport(MIN_VIEWPORT);
		let mut ui = build(model, ctx);
		// The rail starts without the keyboard: no focus chrome or frame
		// cursor until `toggle` or a click hands it over.
		ui.blur();
		Self { ui, options, open: true, focused: false, elapsed_seconds: 0, height: 0 }
	}

examples/gallery/overlay.rs (line 54)

pub(crate) fn show_picker(ui: &mut Ui) -> OverlayId {
	ui.show_overlay(
		dom! {
			<box border=round title="Switch Model">
				<col gap=1>
					<text dim>{"Session-only switch — role models stay unchanged"}</text>
					<select id=model>
						for (value, label, stats) in MODELS {
							<option value={value} desc={stats}>{label}</option>
						}
					</select>
				</col>
			</box>
		},
		OverlayOptions::default()
			.anchor(OverlayAnchor::Center)
			.width(Dim::Pct(70))
			.min_width(48)
			.max_height(Dim::Pct(60))
			.min_viewport(Size::new(40, 8)),
	)
}

pub const fn non_modal(self) -> Self

Leaves keys and paste with the base tree while the layer is visible.

crate::Ui::focus_overlay hands the keyboard to the layer on demand; a click inside its band does the same, and a click outside (or an unconsumed Esc) returns it.

Examples found in repository

examples/chat/sidebar.rs (line 60)

	pub fn new(model: &str, ctx: &UiContext) -> Self {
		let options = OverlayOptions::default()
			.anchor(OverlayAnchor::Right)
			.width(Dim::Cells(WIDTH))
			.non_modal()
			.min_viewport(MIN_VIEWPORT);
		let mut ui = build(model, ctx);
		// The rail starts without the keyboard: no focus chrome or frame
		// cursor until `toggle` or a click hands it over.
		ui.blur();
		Self { ui, options, open: true, focused: false, elapsed_seconds: 0, height: 0 }
	}

pub const fn fill_height(self) -> Self

Stretches a retained overlay tree to the full available viewport height.

Trait Implementations

impl Clone for OverlayOptions

fn clone(&self) -> OverlayOptions

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for OverlayOptions

impl Debug for OverlayOptions

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for OverlayOptions

fn default() -> Self

Returns the “default value” for a type.

impl Eq for OverlayOptions

impl PartialEq for OverlayOptions

fn eq(&self, other: &OverlayOptions) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for OverlayOptions