Struct App 

pub struct App {

    pub data_table_state: Option<DataTableState>,
    pub local_desktop: bool,
    pub home: HomeState,
    pub home_previews: Previews,
    pub reads: ReadCounts,
    pub info_modal: InfoModal,
    pub codebook: Option<Arc<Codebook>>,
    pub catalog_entry: Option<(String, Arc<Dataset>)>,
    pub documentation: DocState,
    pub info_documentation: DocState,
    pub head_web_rows: bool,
    pub find: Find,
    pub input_mode: InputMode,
    pub sort_filter_modal: SortFilterModal,
    pub pivot_melt_modal: PivotMeltModal,
    pub view_modal: ViewModal,
    pub analysis_modal: AnalysisModal,
    pub sample_form: Option<SampleForm>,
    pub chart_modal: ChartModal,
    pub chart_export_modal: ChartExportModal,
    pub export_modal: ExportModal,
    pub copy_modal: CopyModal,
    pub inspector_modal: InspectorModal,
    pub go_to_column: PickerState,
    pub value_counts: ValueCountsModal,
    pub format_picker: PickerState,
    pub retype: Option<RetypeModal>,
    pub combine: Option<CombineModal>,
    pub table_picker: PickerState,
    pub table_choices: Option<Tables>,
    pub hex: Option<HexView>,
    pub confirmation_modal: ConfirmationModal,
    /* private fields */
}

Fields

data_table_state: Option<DataTableState>

local_desktop: bool

Whether a browser opened here opens in front of the user: o on a documentation link is offered only then (link_open::local_desktop).

home: HomeState

Home screen state. Rebuilt from the filesystem whenever home is entered; nothing here is persisted beyond the recents list.

home_previews: Previews

The home screen’s ROWS previews, and the dataset the newest one built.

reads: ReadCounts

The reads of data started this session, by kind.

info_modal: InfoModal

codebook: Option<Arc<Codebook>>

What the dataset’s columns mean, when a catalog that lists it says.

catalog_entry: Option<(String, Arc<Dataset>)>

The catalog entry the open dataset is, or is inside, and its catalog’s label: what Info’s Documentation tab shows.

documentation: DocState

The Documentation view, full screen over home (Ctrl+E).

info_documentation: DocState

The same page for the open dataset, on Info’s Documentation tab.

head_web_rows: bool

Send a HEAD for the HTTP(S) file under the cursor on home, to show its size. Off under cargo test, which never reaches the network unless a test asks.

find: Find

The find prompt (/) and the find n and N repeat; history id “find”.

input_mode: InputMode

sort_filter_modal: SortFilterModal

pivot_melt_modal: PivotMeltModal

view_modal: ViewModal

analysis_modal: AnalysisModal

sample_form: Option<SampleForm>

The Sample form over the table (S): the view’s sample, the step under its query.

chart_modal: ChartModal

chart_export_modal: ChartExportModal

export_modal: ExportModal

copy_modal: CopyModal

inspector_modal: InspectorModal

go_to_column: PickerState

The shown columns, narrowed by what is typed, while g is choosing one.

value_counts: ValueCountsModal

The Value Counts screen (F).

format_picker: PickerState

The specs b offers for the dataset on screen.

retype: Option<RetypeModal>

The type picker, while it is open.

combine: Option<CombineModal>

The combine form, while it is open.

table_picker: PickerState

The tables T offers: the picker’s lines, and what each opens.

table_choices: Option<Tables>

hex: Option<HexView>

The hex view (InputMode::Hex), kept while it is up.

confirmation_modal: ConfirmationModal

Implementations

impl App

pub fn live_on_screen(&self) -> Option<usize>

The matches the prompt’s pattern has among the rows on screen, while the prompt is open.

pub fn live_cells(&self) -> Option<Arc<MatchCells>>

The cells to light up: the prompt’s matches while it is open.

pub fn find_hit(&self) -> Option<(usize, String)>

The cell the find in effect landed on, while the view is the one it searched.

pub fn find_mark(&self) -> Option<String>

What the control bar says about the find in effect: the pattern, and which match the cursor is on when that is known.

pub fn finding(&self) -> bool

Whether a find is reading.

impl App

pub fn hex_view(&self) -> Option<&HexView>

The hex view on screen, if it is.

impl App

pub fn request_reshape_preview(&mut self)

Ask for a preview of the staged spec, unless it is the one already asked for. One worker runs at a time: an edit made while it runs is previewed when it ends.

pub fn reshape_preview_pending(&self) -> bool

Whether the builder’s preview has an answer still to come.

impl App

pub fn pointer(&mut self, mouse: &MouseEvent, now: Instant) -> Pointer

What a mouse event means on the screen last drawn.

pub fn cancel_drag(&mut self)

A key was pressed: a header being carried is put back, and its mark goes.

pub fn forget_click(&mut self)

Forget the last click and any drag: it was dropped, so the next is not its second, and nothing was picked up.

pub fn point(&mut self, target: &Target)

Move the cursor to what a click or the wheel landed on. A press on a header picks the column up, for a drag to move.

pub fn point_for_menu(&mut self, hit: &CellHit) -> bool

Put the cursor on the cell a right click landed on, for the menu. Returns whether it is there: rows that moved since they were drawn are not the ones clicked, and the menu would act on another cell.

pub fn focus_field(&mut self, id: &FieldId) -> Option<Clicked>

Focus the field a click landed on, in whichever form drew it.

pub fn point_at_tool(&mut self, tool: usize)

Put the analysis tools list’s cursor on tool, the list focused, as Tab and the arrows would.

pub fn start_resize(&mut self, column: String, x: u16)

Start a width drag on column, from the width it has now.

pub fn set_dragged_width(&mut self, column: String, width: u16)

Set a column’s width by hand, as < and > do, within their bounds.

impl App

pub fn set_memory_probe(&mut self, probe: MemoryProbe)

Read the memory available now from probe rather than from the system: for a test that decides how much there is.

pub fn sample_drawing(&self) -> bool

Whether the view’s sample is being drawn.

impl App

pub fn what_enter_does(&self) -> WhatEnter

See WhatEnter.

impl App

pub const LOOKING_AT_A_DIRECTORY: &'static str = "Looking at the directory"

The wait while a directory named on the command line is looked at: which files it holds, and whether they are one table. Seconds, for a directory of large Parquet.

pub const LOADING_BUFFER: &'static str = "Loading buffer..."

The wait while the rows for the view are fetched.

pub fn quality_copy_bytes(&self) -> u64

Bytes on disk in the copies kept.

pub fn is_busy(&self) -> bool

Whether keys wait: a job the user is waiting on is running or owed, an errand is between its phases, or an open is on its way to its dataset.

pub fn task_generation(&self) -> u64

The generation background answers are judged by. Advanced each time work starts that replaces what is in flight.

pub fn job_is_current(&self, ticket: Ticket) -> bool

Whether the job ticket names is still running and its answer still wanted.

pub fn use_cache(&mut self, cache: CacheManager)

Keep recents, histories and measurements in cache from now on. For a test that reads its store back: every test in a process shares one, and fifty opens elsewhere push its entries out of the capped recents list.

pub fn use_catalog_dir(&mut self, dir: &Path) -> Result<()>

Read catalog.toml from dir, and write it there, from now on. For a test whose Ctrl+D must not write into the config directory every test in a process shares.

pub fn open_path(&self) -> Option<&Path>

Path of the dataset currently installed, if any. Exposed for tests that need to assert an abandoned load did not swap a dataset in after the fact.

pub fn background_work_in_flight(&self) -> bool

Whether any leased background work, current or abandoned, has yet to report back. Exposed for tests that wait for abandoned work to finish rather than guessing how long it takes.

pub fn screen_generation(&self) -> u64

See the screen_generation field.

pub fn modal_showing(&self) -> bool

True while a message is in front of the user that has to be dismissed.

pub fn follow(&self) -> Option<&Follow>

The follow of the dataset on screen, while it is followed.

pub fn recording(&self) -> Option<&Arc<Spool>>

Standard input being recorded to the file --tee named, for the dataset on screen.

pub fn recording_after_exit(&mut self) -> Option<(Tee, Arc<SpoolHandle>)>

The recording to wait for once the terminal is handed back: kept going when the user quit, until its stream ends.

pub fn flash_message(&self) -> Option<&str>

The completion flash on the control bar, if one is showing.

pub fn error_message(&self) -> Option<&str>

The error dialog’s message, if one is showing.

pub fn next_deadline(&self) -> Option<Instant>

When the screen next changes on its own, with no event to say so: the flash expiring. The run loop sleeps until then at most.

pub fn tick_follow_clock(&mut self) -> bool

Whether the follow chip’s clock reads differently now: the frame must redraw.

pub fn tick_flash(&mut self) -> bool

Drop an expired flash. Returns true when the frame must redraw.

pub fn flash_polars_warning(&mut self) -> bool

Show the next Polars user warning on the control bar, once per session, when the bar is free. Returns true when the frame must redraw.

pub fn flash_background_panic(&mut self) -> bool

Say that a background thread panicked when nothing else did; a job’s panic ends the job instead, the way its error would. Returns true when the frame must redraw.

pub fn set_input_dropped(&mut self, dropped: bool)

See the input_dropped field.

pub fn hard_escape_while_busy(&self, key: &KeyEvent) -> bool

The escapes that act at once while busy and jump ahead of anything queued: Ctrl-Q and Ctrl-C quit, Ctrl-O goes home, so a slow load never traps the user; a confirmation modal keeps its keys so it can be answered; and the home screen is never busy on its own account (only work left running behind it sets busy), so it keeps every key.

pub fn key_acts_while_busy(&self, key: &KeyEvent) -> bool

Whether a key may act while the app is busy. App::handle gates on this; the main loop applies the extra “nothing queued” condition for the second group.

The hard escapes always qualify. Beyond them, in the plain Normal-mode table view (no text field, no modal), the harmless view keys act — quit, the column cursor and help — because the first key held in that view cannot be part of a typed /query. Harmless means reads nothing: the column cursor re-slices the buffer it already holds through rescroll_columns, never collect, which counts the rows when the count has not landed. Admitting a key that can count would put a metadata read per object of a cloud hive on this very thread — a_key_that_acts_while_busy_reads_nothing holds the line. Everything else, letters included, is type-ahead and waits; a bare Enter or Esc there confirms nothing and is dropped by the caller. Nothing is classified by keycode alone: the h in a typed /hello never scrolls.

pub fn in_normal_table_view(&self) -> bool

The plain table view: Normal mode with no help overlay, modal, or in-view modal (view, analysis) or context menu drawn over it.

pub fn open_context_menu(&mut self, at: Position)

Open the context menu at at, over the cell the cursor was just put on.

pub fn close_context_menu(&mut self)

Close the context menu, if it is open.

pub fn choose_from_menu(&mut self, i: usize) -> Option<AppEvent>

The line i of the open menu, chosen: the menu closes and its key is pressed, offered as typed.

pub fn drop_column(&mut self, column: &str, onto: &str) -> Option<AppEvent>

A header dropped on another column: the order with column moved to where onto is, as H / L would leave it pressed that many times. A frozen column moves among the frozen ones only, and a scrolling one among the scrolling.

pub fn text_field_focused(&self) -> bool

Whether a text field currently owns typed characters, so the wheel and ? leave it alone. The home filter is deliberately excluded.

pub fn send_event(&mut self, event: AppEvent) -> Result<()>

pub fn row_count_pending(&self) -> bool

Whether the dataset on screen is one that opened before its footers were read and is still waiting for them.

Not the same question as whether a pass is running. The counter is shared with every open, and abandoning one does not stop it: without this, giving up on a large local directory and going back to the dataset you had would leave that dataset’s control bar counting footers belonging to the directory you left. Whether the row count on the control bar is on its way, so a spinner stands in for it. Asked by the bar, and by the run loop, which turns the spinner: the two disagreed while a dataset read its own footers, and the spinner sat still.

pub fn something_is_spinning(&self) -> bool

Whether a spinner is on screen, so the run loop turns it and redraws.

pub fn footer_progress(&self) -> &Arc<FooterProgress>

The footer counter the screen reads: the open’s own while one is on its way to a dataset, else the dataset on screen’s. Each open counts on its own, so one replaced half way through cannot count under the name of the file that replaced it.

pub fn exit_sweep(&self) -> ExitSweep

Hold past the app: dropped after it, it removes the temp files the app’s opens were still writing, giving their workers up to a second to stop first. Without it, a quit mid-download or mid-decompression can end the process before the worker removes its partial file.

pub fn set_loading_phase( &mut self, phase: impl Into<String>, progress_percent: u16, )

An open is on its way: the loading screen takes over now, saying phase, and keys wait for it. Called before the event that carries the open out — by run before the first frame, and by a key before the Open it returns — because a frame is drawn between the two and would otherwise show the outgoing dataset.

pub fn spawn_async_collect(&mut self, status: &str) -> bool

Ensures file path has an extension when user did not provide one; only adds compression suffix (e.g. .gz) when compression is selected. If the user provided a path with an extension (e.g. foo.feather), that extension is kept. Spawn an async buffer collect if needed. Returns true if a background task was spawned. Increments task_generation to invalidate any in-flight collect from a prior call.

When the LazyFrame’s row count is unknown (e.g. fresh load, or just after a filter/sort/pivot/melt that invalidates the cache), the exact len() is computed in the background and applied later via BackgroundLenReady — it never gates the buffer paint. prepare_async_collect plans a top-of-data window when the count is still unknown, so the first screen renders immediately. For large/partitioned/remote datasets the count can take a long time; it runs silently and concurrently.

pub fn count_waits_for_a_frame(&self) -> bool

Whether a frame painted now would start, or retire, the count waiting on one. The run loop paints after every update; a test harness, which paints nothing, asks this to know when to say a frame was painted.

pub fn frame_painted(&mut self)

A frame has been painted. Start the count that was waiting for its rows to be on screen, unless they are still being read; retire it if the frame it was for has gone or its rows already said how many there are.

pub fn new(events: Sender<AppEvent>, runtime: Handle) -> App

pub fn new_with_theme( events: Sender<AppEvent>, runtime: Handle, theme: Theme, ) -> App

pub fn new_with_config( events: Sender<AppEvent>, runtime: Handle, theme: Theme, app_config: AppConfig, ) -> App

An app with its saved views read here, before it is returned.

pub fn new_with_views( events: Sender<AppEvent>, runtime: Handle, theme: Theme, app_config: AppConfig, view_manager: Views, ) -> App

An app whose saved views may still be on their way (Views).

pub fn set_formats(&mut self, registry: Registry)

Use registry as the format specs on the search path, for hosts and tests that have their specs in hand.

pub fn enable_debug(&mut self)

pub fn home_schema(&mut self, entry: &Entry) -> Option<SchemaPreview>

Schema for a home-screen entry, read from Parquet metadata and memoised for the session. None means “not knowable without a scan”, which the UI reports rather than papering over.

pub fn home_preview_rows( &mut self, entry: &Entry, screen_height: u16, ) -> Option<Arc<PreviewRows>>

The first rows of a home-screen file for its ROWS preview, read on a worker the way its open reads them. None until they land, and for a row that is not previewed. screen_height sizes the page to the one the table will ask for.

pub fn home_preview_pending(&self, path: &Path) -> bool

Whether entry is one the preview reads, before its rows are in.

pub fn home_schema_pending(&self, path: &Path) -> bool

Whether a schema read is currently out for this path.

pub fn request_what_the_frame_needs(&mut self)

Ask for what the frame just drawn needs and did not have: counts for the rows on screen that have none, and kinds for the rows nothing has looked into.

After the frame, never during it. Scrolling is what brings new rows into view, and the reading is a worker’s job — this thread only decides what is worth asking about.

pub fn abandon_load(&mut self)

Enter the home screen, rebuilding it, abandoning any in-flight load.

Returning home puts the cursor on whatever you currently have open, so the round trip out and back lands where you left rather than at the top.

Abandoning puts the open in flight down at once ([loading::Loader::retire]): its jobs are superseded, so their answers are dropped on arrival and none can install a dataset or take the user off the screen they went to; its stop flag is raised, so a download stops and an in-flight cloud pass stops issuing paid reads within a wave. Work that is not the open’s — an export, an analysis, the footer pass of the dataset already on screen — is deliberately left alone, so its progress indicator and its completion modal must survive this.

pub fn enter_home(&mut self)

pub fn route_named_paths(paths: Vec<PathBuf>, options: OpenOptions) -> AppEvent

What datui <path> does with a directory: the same rule as Enter on its row.

A directory used to be Unsupported file type unless --hive was passed, while pyarrow, Polars, pandas and Spark all open one. Naming a directory is the request to read it, so the three doors onto a path — the highlighted row, the ~ prompt and the command line — now answer the same: a hive root or a directory whose files are one table opens as one table, and a directory that is a place to look inside opens the home screen browsed into it, one keystroke from either file or union.

The directory is looked into rather than guessed at, because that is what the rule is: home::look_into is the same call the home screen’s background pass makes, footers and all.

--hive is untouched. It names a glob or forces partition columns, and it is still the only way to say “read this as partitioned” about something whose layout does not say so itself.

Asks the filesystem whether a local path is a directory, so run calls it on a worker (AppEvent::OpenNamed). Returns the event that carries the open on: LookThenOpenDirectory or Open.

pub fn route_named_paths_with( paths: Vec<PathBuf>, options: OpenOptions, formats: &Registry, ) -> AppEvent

Self::route_named_paths, with the format specs on the search path: a directory a spec reads as column files is opened, not looked at.

pub fn missing_named_path( paths: &[PathBuf], formats: &Registry, ) -> Option<PathBuf>

The first named local path that is not there. A URL or a glob is left to the open, which says what it found, and standard input is no path.

impl App

pub fn help_visible(&self) -> bool

Whether the help overlay is on screen.

pub fn help_context(&self) -> Option<Context>

The screen the help overlay shows the keys of, while it is up.

pub fn keys_context(&self) -> Context

The screen the keys typed now go to, as the key registry names it.

pub fn awaiting_open_confirmation(&self) -> bool

True while the confirmation modal is asking whether to download a remote file, or to read a large one whole into memory.

Those are the confirmations the user has to be able to walk away from: the size probe behind a download can take fifteen seconds, and the answer to “actually, never mind” is the home screen, not the exit.

pub fn handle(&mut self, event: &AppEvent) -> EventOutcome

Handle one event. A key that arrives while the app is busy is not acted on and not dropped either: it comes back as Err(key) for the caller to hold until the app is idle. The main loop (event_pump::EventPump) does exactly that; App::event is the same call for callers that have nowhere to hold a key.

pub fn event(&mut self, event: &AppEvent) -> Option<AppEvent>

pub fn chart_preparing(&self) -> bool

True while chart data for the current view is being prepared off-thread — either its worker is running, or it is waiting its turn behind an orphaned worker that cannot be cancelled (see ChartInflight::stale). Either way the user is waiting on a computation and the throbber should say so.

pub fn chart_names(&self) -> Option<Vec<String>>

The series of the line or scatter chart on screen, by name, once prepared: its Y columns or its color groups.

pub fn chart_data_ready(&self) -> bool

True when the chart cache holds the data for the modal’s current selection.

pub fn header_toggle_offered(&self) -> bool

Whether the dataset on screen is delimited text, whose first row H on the Info panel’s Schema tab reads the other way.

pub fn unfit_count_pending(&self) -> bool

Whether the values the read’s column types made null are being counted.

pub fn file_facts(&self) -> Option<&FileFacts>

What the Info panel knows about the open file: None until it is asked, and for a source with no file on this machine. Installing a dataset clears it, so what is here is the open dataset’s.

pub fn python_script(&self, state: &DataTableState) -> String

The view on screen as a Python Polars script: the open’s reader, then every step that made the view. See python_script.

pub fn enter_inspects(&self) -> bool

Whether Enter at the table opens the inspector, as Space does: there is a table, and it is not one whose rows drill into groups (a by view, a SQL GROUP BY). Inside a drill-down there is nothing further to drill into either.

pub fn sibling_tables(&self) -> Option<Tables>

The tables of the source on screen, from what its open holds; None for a source of one.

pub fn offers_other_tables(&self) -> bool

Whether the source on screen has another table for T to open.

pub fn follow_terminal_background(&mut self, mode: ThemeMode)

Under theme.mode = "auto", switch to the theme for the terminal’s background (theme.dark or theme.light), keeping the configured theme.colors over it as at startup. An explicit mode ignores the terminal.

pub fn settle_first_palette(&mut self, answered: Option<ThemeMode>)

Settle the palette of the first frame under auto, without waiting for the terminal: its answer when answered has it, else what this terminal answered last time. An answer that comes later switches palettes if it differs.

pub fn take_background_query(&mut self) -> bool

Whether the run loop should ask the terminal for its background, once. Asked by AppEvent::TerminalFocused under auto.

pub fn theme(&self) -> &Theme

The colors the next frame is drawn with.

pub fn follows_terminal(&self) -> bool

Whether the palette follows the terminal (theme.mode = "auto").

pub fn take_external_open(&mut self) -> Option<ExternalOpen>

The value the inspector wrote for another program, for the run loop.

pub fn mouse_enabled(&self) -> bool

Whether the session reports the mouse, to take it again after a program had the terminal.

pub fn external_opened(&mut self, open: &ExternalOpen, failed: Option<String>)

The run loop opened open: a program that waited is done with its file; a failure is said on the bar.

pub fn set_clipboard_destination(&mut self, destination: Box<dyn Destination>)

Replace the clipboard destination, so tests can watch what a copy sends without a display server or a terminal in the loop.

pub fn create_view_from_current_state( &mut self, name: String, description: Option<String>, match_criteria: MatchCriteria, ) -> Result<SavedView>

pub fn query_prompt_mode(&self) -> Option<QueryMode>

The command line’s language while it is open.

pub fn query_prompt_text(&self) -> Option<&str>

The command line’s text, while it is open.

pub fn query_prompt_error(&self) -> Option<String>

Why the last run failed, for the line under the input: a statement that failed while running, else one that could not be planned.

pub fn inline_failures(&self) -> u64

Bumped each time a running statement’s failure is put in the prompt.

impl App

pub fn capture_view(&self) -> Result<Option<LazyFrame>>

The view a caller that asked for one gets back when the app exits (datui.view(..., capture=True)): the active table’s committed frame with datui’s internal columns dropped. None when no dataset is open. Text still sitting in an editor was never applied, so it is not here either.

Refused when the frame would scan a temporary file, because those are removed on exit and a plan over deleted paths fails later and worse: a remote download, a decompressed archive, or a converted stream or GPS log. The in-TUI export (e) writes real rows and is the way out for those datasets.

Trait Implementations

impl Drop for App

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl Widget for &mut App

fn render(self, area: Rect, buf: &mut Buffer)

Draws the current state of the widget in the given buffer. That is the only method required to implement a custom widget.