Struct Shell 

pub struct Shell<D> { /* private fields */ }

The window frame. Hold one as the app’s root; call ui every frame.

Labels are message ids: each frame the hover text is looked up in the language installed (see i18n), so a language switch shows on the next frame.

The shell keeps clear of the system’s bars and notches (egui’s safe area, which iOS fills): the rail, the bar’s buttons and the screens stay inside it, and the bottom bar’s fill runs on under the home indicator, as a phone’s tab bar does. Give it the window’s whole root ui; the app adds no margin of its own. If the app does keep ui clear of them itself, the shell sees that and adds nothing, so the margin is never doubled. On Android, window::run_android keeps the app’s ui clear of the bars and the keyboard already.

#[derive(Clone, Copy, PartialEq)]
enum Screen { Gallery, Albums, Settings }

let mut shell = Shell::from_items(vec![
    Action::new("import", icons::plus(), "import").into(),
    // The app's own Lucide SVGs: `egui::include_image!("../assets/icons/images.svg")`.
    Destination::new(Screen::Gallery, icons::folder(), "gallery").into(),
    Destination::new(Screen::Albums, icons::folder(), "albums").into(),
])
.with_footer(vec![Destination::new(Screen::Settings, icons::settings(), "settings")]);
shell.ui(ui, |ui, screen| match screen {
    Screen::Gallery => { egui::CentralPanel::default().show(ui, |ui| ui.label("…")); }
    Screen::Albums => { egui::CentralPanel::default().show(ui, |ui| ui.label("…")); }
    Screen::Settings => { egui::CentralPanel::default().show(ui, |ui| ui.label("…")); }
});
if shell.take_action() == Some("import") {
    // …
}

Implementations

impl<D: Copy + PartialEq> Shell<D>

pub fn new(destinations: Vec<Destination<D>>) -> Shell<D>

A frame with destinations on the rail, the first one open.

pub fn from_items(items: Vec<RailItem<D>>) -> Shell<D>

A frame with items — screens and actions — on the rail in this order, the first screen open.

pub fn with_actions(self, actions: Vec<Action>) -> Shell<D>

Put actions on the rail after the items already there. To put one first, give the items to from_items instead.

pub fn with_footer(self, footer: Vec<Destination<D>>) -> Shell<D>

Put footer at the rail’s foot (at the bottom bar’s end): where an app puts Settings. With no other destinations, the first of these is open. When some items are left off the rail, the footer moves into the More menu, which takes its place.

pub fn with_rail_order(self, order: &RailOrder) -> Shell<D>

Lay the rail out in order, as set_rail_order.

pub fn rail_order(&self) -> RailOrder

The order the rail’s items are in, and which of them it leaves to the menu.

pub fn set_rail_order(&mut self, order: &RailOrder)

Lay the rail out in order. With the serde feature and a store attached, the order saved there replaces this on the first frame.

pub fn take_action(&mut self) -> Option<&'static str>

The Action clicked in the last ui, once: call it after ui every frame and do what it names.

pub fn current(&self) -> Option<D>

The destination that is open; None only when there are none.

pub fn open(&mut self, id: D)

Open the destination id.

pub fn with_side_pane(self) -> Shell<D>

Give the app a side pane: a right column beside every screen when wide, which the status bar’s button hides; a card over the screen when it is hidden or there is no room; on a phone, the screen’s place. ShellApp::side_ui fills it, and a screen or an action opens it through Side. Whether the column is on is kept with the rail’s order, in the store if one is attached.

pub fn with_status_bar(self) -> Shell<D>

Draw a status bar along the window’s bottom when wide: ShellApp::status_ui fills it from the left — a log’s last line, the services’ state, the track playing; its right end holds ShellApp::foot_ui (there rather than at the rail’s foot), then the side pane’s toggle. Narrow, as on a phone, there is no status bar: the foot stays on the bottom bar.

pub fn show(&mut self, ui: &mut Ui, app: &mut impl ShellApp<D>)

Render app into the window’s root ui: the rail, the open screen (ShellApp::screen_ui) and, with_side_pane, the side pane beside it; then hand an action clicked to ShellApp::action. The first frame installs the default theme and language if the app has not installed them, and takes the rail’s order and the side column from the store if one is attached.

pub fn ui(&mut self, ui: &mut Ui, content: impl FnOnce(&mut Ui, D))

Render into the window’s root ui. content draws the open destination into what the frame leaves of ui, as it would at the root: its own panels, then a CentralPanel. An action clicked waits for take_action. The first frame installs the default theme and language if the app has not installed them, and takes the rail’s order from the store if one is attached. An app with a side pane or state shared by its screens implements ShellApp and calls show.

pub fn ui_with_foot( &mut self, ui: &mut Ui, foot: impl FnOnce(&mut Ui) -> Option<D>, content: impl FnOnce(&mut Ui, D), )

As ui, with foot drawn beside the footer — a status dot, say. A destination foot returns is opened, and drawn this frame.

pub fn ui_with_status( &mut self, ui: &mut Ui, foot: impl FnOnce(&mut Ui) -> Option<D>, status: impl FnOnce(&mut Ui), content: impl FnOnce(&mut Ui, D), )

As ui_with_foot, with a status bar along the window’s bottom when wide, as with_status_bar: status fills it from the left, and its right end holds foot. Narrow, as on a phone, there is no status bar: foot stays on the bottom bar, and status is not called.