UI Guide

Use this page when choosing widget display chrome for notebooks, exported HTML, reports, and GIF-like visuals. Maintainer-only frontend wording and review rules live in Widget UI protocol.

UI Modes

Preset	Why it exists	Behavior
ui_mode="interactive"	Normal notebook analysis.	Full widget UI, controls open, default annotations visible.
ui_mode="presentation"	Shared HTML that should open cleanly but remain adjustable.	Controls start collapsed behind Controls; stats, resize handles, and zoom badges are hidden where supported. Titles, panel labels, and scale bars stay visible.
ui_mode="report"	Clean figure in a report or manuscript-style notebook.	Controls are removed with no GUI recovery button; stats, resize handles, and zoom badges are hidden. Titles, panel labels, and scale bars stay visible.
ui_mode="minimal"	Bare visual/GIF-like output.	Title, controls, stats, panel titles, scale bars, resize handles, zoom badges, and equivalent optional chrome are hidden where supported.

Explicit keyword arguments override the preset:

Show3D(
    data,
    ui_mode="presentation",
    show_panel_titles=True,
    show_scale_bar=True,
)

Common Controls

Name	Widgets	Meaning
show_title	Show1D, Show2D, Show3D, Show3DSlices, Show4DSTEM, ShowEDS, ShowDiffraction	Show or hide the top title row.
show_controls	Show1D, Show2D, Show3D, Show3DSlices, Show4DSTEM, ShowEDS, ShowDiffraction	Expose controls at all. Set False for a permanently clean display with no GUI recovery button.
controls_collapsed	Show1D, Show2D, Show3D, Show3DSlices, Show4DSTEM, ShowEDS, ShowDiffraction	Start with controls hidden. Show4DSTEM exposes this as programmatic/state control only; other widgets may also show a top Controls button.
collapse_controls()	Show1D, Show2D, Show3D, Show3DSlices, Show4DSTEM, ShowEDS, ShowDiffraction	Programmatically collapse controls.
expand_controls()	Show1D, Show2D, Show3D, Show3DSlices, Show4DSTEM, ShowEDS, ShowDiffraction	Programmatically expand controls.
toggle_controls()	Show1D, Show2D, Show3D, Show3DSlices, Show4DSTEM, ShowEDS, ShowDiffraction	Programmatically toggle collapsed controls.
show_stats	Show1D, Show2D, Show3D, Show3DSlices, Show4DSTEM, ShowDiffraction	Show or hide mean/min/max/std readouts where the widget renders or computes them.
show_panel_titles	Show2D, Show3D	Show labels on individual image/volume panels.
panel_title_font_size	Show2D, Show3D	Font size for per-panel labels.
show_scale_bar	Show2D, Show3D, Show3DSlices, Show4DSTEM, ShowEDS	Show or hide scale bars. Some widgets keep the saved-state trait name scale_bar_visible for compatibility.
show_resize_handles	Show3D	Show or hide resize handles. Show2D hides resize handles automatically when controls are collapsed.
show_zoom_indicator	Show3D	Show or hide the zoom readout.
show_legend	Show1D	Show or hide trace legends.
show_grid	Show1D	Show or hide plot grid lines.
show_crosshair	Show3DSlices	Show or hide slice intersection guides.

Recommended Uses

Goal	Recommended API	Why
Interactive notebook exploration	ui_mode="interactive"	Keeps every control available for analysis.
Shared HTML with a clean first view	ui_mode="presentation"	Starts uncluttered while preserving a Controls button for collaborators.
Report figure with labels and scale context	ui_mode="report"	Removes GUI controls while preserving scientific context.
GIF-like visual with no chrome	ui_mode="minimal"	Hides title, controls, stats, panel labels, scale bars, and similar annotations.

Prefer explicit overrides instead of one-off names. For example, use show_scale_bar=False rather than widget-specific spellings like hide_scalebar=True.