Skip to content

Latest commit

 

History

History
391 lines (313 loc) · 29.5 KB

data-views.md

File metadata and controls

391 lines (313 loc) · 29.5 KB

Tables, graphs and meters

What a monitor or a list of records shows: values over time and their graphs, a bar of how full something is, a sortable table, and a filter that takes what the user types anywhere in the window. All are in the ui package.

Values over time (src/ui/line_graph.odin)

Value_History(N) keeps the last N values pushed, oldest first. It allocates nothing.

cpu: ui.Value_History(60)
ui.value_history_push(&cpu, percent)              // once per sample
ui.value_history_last(&cpu)                       // the newest (0 when there is none)
ui.value_history_max(&cpu)
ui.value_history_at(&cpu, i)                      // 0 ..< cpu.count, oldest first
ui.value_history_values(&cpu)                     // a copy, oldest first (temp allocator): a series of a graph
ui.value_history_clear(&cpu)

line_graph(id, series, o) draws one or more series in the box that next gives. Each series is an area under its line, filled with its colour fading to the bottom. The newest value is at the right edge. The grid and the frame use the theme's border colour; in the machined finish a graph with a grid is a well (a screen set in the surface).

ui.next({width = ui.fill(), height = ui.px(em * 12)})
ui.line_graph("###disk", {
	{ui.value_history_values(&disk.read), ui.color("accent")},
	{ui.value_history_values(&disk.write), purple},
}, {floor = 1e6, points = 60, grid = true})
Line_Graph_Options
top the value at the top. 0: graph_top of the largest value shown, at least floor
floor what the found top is at least (0: 1). A disk at rest with a floor of 1 MB/s does not fill the graph with noise
points values across the width (0: the longest series'). A history that is not full yet starts at the right
grid grid lines and a frame
columns, rows spaces of the grid (0: 10 and 4)

line_graph_top(series, o) is the top the graph shows: the caption of the graph says it. graph_top(v, floor) is a round value at or above v: 1, 2 or 5 times a power of ten, at least floor.

sparkline(id, series, top, points, floor) is a line graph with no grid and no frame, for a list of devices.

A meter bar

meter_bar(id, used, alert) is a flat bar of how full something is (used from 0 to 1): the theme's accent on its border colour. Past alert the bar takes the colour of the bad tag. It has no animation: it shows the last sample. Screen readers read it as a progress indicator in percent. In the machined finish it is a slot carved in the surface, its run a lit face.

ui.next({width = ui.fill(), height = ui.px(max(3, em * 0.25))})
ui.meter_bar("###memory", used_share, 0.9)

Tests: tests/status/line_graph_test.odin.

Sortable tables (src/ui/table.odin)

A table has two layers. A program that builds its own rows (groups, tinted cells) uses the first; a table of texts uses both.

The layout, the header and the cells

Table_Layout holds the columns (Table_Column), their widths now in ems, which are shown, their order (order, the first column always first), the sort column (TABLE_UNSORTED: none) and its direction. A program saves it and reads it back.

Table_Column
title the header's text
width in ems; 0: the room the other columns leave (one column has it)
number right-aligned; sorted by the row's number; the first click sorts the largest first
low_first a number that the first click sorts from the lowest (an id)
weak its text in the weak colour (details beside the name)
hidden not shown until the user asks for it
Procedure
table_layout_init(l, columns, sort, descending), table_layout_destroy(l) the widths and the shown columns from the columns' own
table_layout_reset(l) the columns' own widths, visibility and order back (the "Default columns" of a menu)
table_layout_move(l, k, to) moves column k to place to of order (from 1: the first column stays first)
table_layout_toggle(l, k) shows or hides column k (never the first); true when the sort moved to the first column
table_header(id, l, lead_em, o) the titles: a click sorts by a column, a second click reverses it, a third leaves the rows in the data's own order (table_sort_click, TABLE_UNSORTED); a title dragged sideways moves its column (not the first), a line in the accent's colour where it will go, and its release is no click; the rule at a column's right edge, dragged, resizes that column and moves those after it (the fill column takes its width of the moment at the first drag: then the table scrolls when wider than its room); the sort's arrow at the title's end. Returns sorted, resized (a rule let go: save the layout), moved (a column moved: save the layout) and menu (a right click on the header). next may set the header's background and height. opts (Table_Header_Options): lead builds in the room before the first title (a box that checks every row), title in each title after its words (a filter's funnel; hot: the pointer is on the title); a column with unsorted sorts nothing when its title is clicked; one with descending_first (a date) sorts from the largest at its first click, as a number does
table_widths_text(l, keys), table_widths_apply(l, keys, text) the widths that are not the columns' own, as a preference's text (pid=6.5,command=30, in ems; keys[k] names column k), and back (bounded; a name it does not know is skipped)
table_order_text(l, keys), table_order_apply(l, keys, text) the columns' order as a text (name,cpu,pid), and back: the columns it names take their places in its order, the others stay where they are, a name it does not know is skipped
table_sort_text(l, keys), table_sort_apply(l, keys, text) the sort as a text (memory, -memory when descending, none unsorted), and back (only to a column shown)
table_column_reset(l, k), table_menu_items(l, labels) a column back to its own width, unsorted when the rows went by it; the header's menu, opened on menu: the right-clicked column's reset (Table_Layout.menu_column), unsorted, the columns shown, the default columns (table_menu_default_labels: the toolkit's words, in the language in use). changed: save the layout; sort_changed: sort again
table_column_items(l) the columns' menu items, in the caller's menu: each column but the first, in their order, checked when shown
table_min_width(l), table_scroll_sync(l, header, list) the least width of a row (the columns shown, the fill column's least, the last rule's grip); the rows' sideways scroll given to the titles in the same build, and the room their list keeps for its scroll bar (the titles leave it: the columns line up). A table narrower than its columns scrolls sideways (Shift+wheel, a touchpad): table_build does it; a program that builds its rows gives its list View_Scroll_X, Allow_Overflow_X and its rows fill_least(table_min_width(l)), then calls table_scroll_sync
table_width(l, k) a column's width: its own, or for the fill column what the others leave, never under TABLE_FILL_MIN_EM (fill_least, resolved in the same build) (too narrow a window: the last columns go past the edge, cut, instead of the fill column going to nothing). A cell a program builds itself takes it
table_cell(l, col, text, bg, fg, border) a cell under its title, each word of Table_Layout.highlight lit where it is (word_ranges, the theme's match on match_bg; table_apply sets it to the filter), clipped to the column, on a background bg with its text in fg and a 1 px outline in border (each optional: a busy cell's tint, the text that reads on it, a stronger shade of the tint). True when the pointer is on it and its text is cut
table_cell_tip(row, text) the cut text, in a tooltip beside the pointer after Feel.tooltip_delay_ms (feel.md)
table_row_end() the room at the end of a row under the last rule's grip, as the titles have (the scroll bar's own room is the list's layout's)
text_cut_under_mouse(b, text, pad) the test of table_cell, for a cell a program builds itself
label_tip(text) a label outside a table that does the same: its whole text in a tooltip when it is cut (widgets.md)
text_shown(text) a text with a zero-width space between two #: a ## would end the shown part of an id

More than one row (src/ui/item_selection.odin, src/ui/list.odin)

Every list (list, vlist, the rows a program builds with list_row, a Table's rows) keeps its selection in an Item_Selection (List_State.selection, its fields promoted): sel, the active row (the cursor), and with multi the rows selected, by identity. The design and its reasons: src/md/features/selection.md.

With multi set:

Gesture Selection
click the row alone; the anchor goes to it
Ctrl+click the row toggled; the anchor goes to it
Shift+click the range from the anchor to the row, alone (a second Shift+click replaces the range)
Ctrl+Shift+click the range added to what was selected when the anchor was set
right click outside the selection: the row alone; on a selected row: the selection stays (its menu acts on it)
Up, Down, Page Up, Page Down, Home, End the cursor moves, its row alone
the same with Shift, with Ctrl+Shift the range from the anchor to the cursor, alone or added
the same with Ctrl the cursor moves, the selection stays
Ctrl+Space the cursor's row toggled
Ctrl+A every row that can be selected
Escape several rows selected: the cursor's row alone; one row or none: cancelled (the program's Escape)

A selected row is drawn with the selected tags. A row is selected by its identity: a vlist's id (it leaves the selection when its row is no longer in the ids: gone or filtered out), a list's index. Without multi, the selection is the active row; a key with Ctrl or Shift is then the program's. table_keys gives Shift+arrows a range from a filter field when vl.multi.

Procedure
list_is_selected(st, i), list_selected_count(st) whether row i is selected; how many are
list_selected_ids(st, allocator) the identities selected, in the rows' order (a pass over the rows: on an action)
list_set_selected(st, i, on), list_select_all(st), list_selection_clear(st) the program's own changes (its Ctrl+A when another field has the keyboard)
st.selected_changed, st.version the build changed the selection; a number that moves with each change of the rows selected (a swap at the same count too) and of the active row: a cache's key, and the version of a palette's disabled that follows the selection (a Virtual_List's and a Table's too: their List_State's)
list_row_id(st, i), list_rows(st) the identity a row is selected by; the rows as the model sees them

A program that builds its own grid or list (a grid of thumbnails, where Up goes a whole line of columns up) keeps an Item_Selection and calls the model with its rows (Item_Rows{count, ids, selectable}):

Procedure
item_selection_click(sel, rows, i, mods), item_selection_context(sel, rows, i) a press, a right click on row i
item_selection_move(sel, rows, to, mods) the cursor goes to to, a row the grid computed; the modifiers say what that does to the selection
item_selection_key(sel, rows, key, mods, page) a list's key (the moves by rows, Ctrl+Space, Ctrl+A, Escape); whether it was the selection's
item_selection_toggle, item_selection_range(sel, rows, i, add), item_selection_one, item_selection_all, item_selection_clear, item_selection_set the steps the gestures are made of
item_selection_has, item_selection_count, item_selection_ids, item_selection_keep(sel, rows) read it; drop the identities no longer in the rows
item_selection_escape(sel, rows, mods) a program's own Escape (its list without the keyboard): on several rows the cursor's alone and true; else false, the Escape is the program's
item_selection_rekey(sel, old_id, new_id) a row's identity changed (a row unfolded whose id carries its height): its selection, base place and anchor follow
item_rows_id, item_rows_selectable, item_rows_next, item_rows_find the rows: an identity, whether a row can be selected, the next one that can, the row of an identity

A long list's cost (src/ui/vlist.odin)

A vlist builds the rows in view only. The rows' heights are in a Fenwick tree, so a build does no pass over the rows unless the ids change. With n rows:

Work Cost
a build with the same ids, rows measured or not O(log n) per row built: each row measured at a new height is a point update
a new average height (the estimate of the rows never measured) nothing: it is applied when a top is asked
new ids (another slice, another ids_version, another count), vlist_invalidate, a new width, scale or font size one pass over the rows: the copy of the ids and every row placed again
vlist_row_top(st, i), vlist_total(st), vlist_row_extent(st, i), vlist_row_at(st, y) O(log n)

vlist(id, st, ids, labels, selectable, ids_version): with ids_version 0 the list compares the ids with the last build's (one memcmp, a pass over the rows); a program that keeps its ids passes a count it raises at each change of them, and the list compares nothing. Pass nil labels with no type-ahead and nil selectable when every row can be selected: neither is then read per row. offsets_made counts the builds that placed every row again. The tree holds 16 bytes per row (a height and whether it was measured, in f64: a million rows add up without drift).

Procedure
vlist_row_top(st, i) the top of row i in the content: the heights above it, measured or estimated; i = the row count gives the total
vlist_total(st) the content's height
vlist_row_extent(st, i) the top and the height of row i
vlist_row_at(st, y) the row at content position y: the last whose top is at or above y

A program that builds its rows itself (its own look, no list_row) names each row vlist_row_name(i): the list measures the rows under that name. list_select(&st.list, i) makes a row active and brings it into view, for a list whose keys are read elsewhere (a palette's field keeps the keyboard).

The first build of a list comes before its layout: the list takes the window's height for its view, and builds more rows than it shows. Its Vlist_Rows.guessed says so, and the list asks for the next build, which has the real rows. A program that fetches the rows it builds (from a disk, a process, a plugin) skips a guessed build.

Stripes, rules and a row's tint

Two fields of the list's state (List_State, so a vlist's and a Table's vl too) set the look of its rows: zebra shades every second row (the theme's list_row zebra background, a step off the page toward the text), rules draws a hairline under each row (rule border). The selected rows keep the selection's colours. list_row(st, i, label, selectable, tint) takes a tint: the row's background in place of its stripe (a row that just came, a row in alert).

app.table.vl.zebra, app.table.vl.rules = true, true
row := ui.list_row(&app.vl, i, label, tint = is_new ? green_flash : nil)

A program's own motion (that flash fading) asks animations_on() first (false when the desktop asks for less motion), draws from the clock (now_ms) and calls keep_animating() while it still moves: the frames stop when it stops.

The table of texts

Table_Data holds the rows of one reading: each cell's text (in the data's arena), the number a numeric column sorts by, each row's identity, what the filter looks in, and its tone (Normal, Dim: the weak tag, Bad: the bad tag). Table is a Table_Layout with the rows shown and the virtual list that builds only the rows in view.

SERVICE_COLUMNS := [?]ui.Table_Column{{title = "Name", width = 18}, {title = "Description", width = 0, weak = true}, {title = "PID", width = 5, number = true}}
ui.table_init(&view.table, SERVICE_COLUMNS[:])

// a new reading
ui.table_data_reset(&view.data, len(SERVICE_COLUMNS))
for u in units {
	ui.table_data_row(&view.data, id_of(u.name), strings.join({u.name, u.description}, " ", context.temp_allocator), u.failed ? .Bad : .Normal)
	ui.table_data_cell(&view.data, u.name)
	ui.table_data_cell(&view.data, u.description)
	ui.table_data_cell(&view.data, pid_text(u.pid), f64(u.pid))
}
ui.table_apply(&view.table, &view.data, query)

// in the build
key_ev := ui.table_keys(&view.table)                   // when no menu or dialog is open
ev := ui.table_build("###services", &view.table, &view.data, query != "" ? "Nothing matches." : "No service.")
if ev.sorted { ui.table_apply(&view.table, &view.data, query) }
if ev.menu || key_ev.menu { open_menu(ev.menu ? ev.menu_at : key_ev.menu_at) }
Procedure
table_data_reset(d, cols), table_data_destroy(d), table_data_count(d)
table_data_row(d, id, search, tone, group), then table_data_cell(d, text, num) once per column a row; search is what the filter finds it by; the rows of a lower group come first in every sort, unsorted too (a file manager's folders)
table_data_text(d, row, col), table_data_clone(d, text) a cell's text; a copy that lives as long as the rows
table_init(t, columns, sort, descending), table_destroy(t)
table_apply(t, d, query) filters (the query in each row's search text, case ignored; with Table_Layout.fuzzy, the query's letters in that order, as fuzzy_score finds them, the cells lighting the letters matched) and sorts again: texts with ascii.compare_fold, numbers by their value, ties by the first column, the groups in their order. The selected row stays selected when it is shown; a new filter selects its first row
table_selected(t) the data row selected, -1 for none
table_select_id(t, id) selects a row by its identity and brings it into view
table_keys(t) Up, Down, Page Up, Page Down, Ctrl+Home, Ctrl+End move the selection while the keyboard is elsewhere (a filter field); Enter activates; the Menu key and Shift+F10 ask for the row's menu under the selected row (keyboard is true)
table_build(id, t, d, empty) the header and the rows. A cut cell shows its whole text in a tooltip. The selection is drawn strong while the window is the user's (inactive is false), whatever has the keyboard. empty: what the table says with no row
table_label(d, row) what a screen reader says of a row: its first two cells

Table_Events: menu and menu_at (a right click on a row selects it), keyboard, activated (a double click or Enter), sorted, resized, columns (a right click on the header). Table.lead(t, row, size), when set, builds what goes before the first cell's text, size high (an icon; in a taller row, a thumbnail whose width the lead chooses); lead_user is the caller's. Table.lead_em is the room before the first title and the first cell (0: 0.6 em). Table.row_em is a row's height in ems (0: TABLE_ROW_EM): taller rows for a lead that shows a picture. Table.header_bg is the header's background (nil: none). A name edited in place (a rename): while Table.editing, the row of identity Table.edit_id has, in place of its first cell's text (or its card's name, in every view), what Table.edit(t, row) builds: a line_edit the caller owns, which takes the keyboard and reads Enter itself. The caller ends it (editing = false); the file browser's Rename does so.

A table's views (src/ui/table_views.odin)

The same rows show in four views: Details (the header and the columns), List (the first column alone), Columns (the names column by column, scrolled sideways) and Grid (cards: a picture, the name, a weak line). Table.zoom is one index over seven steps, from the densest: Details, List, Columns, then cards of 8.5, 11.5, 15 and 20 ems. A table starts in Details. The filter, the sort and the selection are the same in every view: vl.sel, list_selected_ids(&t.vl) and table_selected read the items whatever the view, and vl.key is the box of the view that has the keyboard.

view.table.zoom_keys = true                // Ctrl+wheel and Ctrl+= / Ctrl+- / Ctrl+0 over the table step its zoom
view.table.rubber_band = true              // multi: a press on the empty part and a drag select a rectangle
view.table.card_line = SIZE_COLUMN         // a card's weak line
view.table.picture = file_thumbnail        // a card's picture (else the lead, its font at table_card_icon_size)
if z, ok := ui.table_zoom_from_key(saved); ok { view.table.zoom = z }

ev := ui.table_build("###files", &view.table, &view.data, empty)
if ev.zoomed { save(ui.table_zoom_key(view.table.zoom)) }
Procedure
table_zoom_step(i) step i's Table_Zoom: its view and its cards' width in ems (TABLE_ZOOMS steps; TABLE_ZOOM_CARDS: the cards of table_set_view(.Grid))
table_view(t) the view of the table's step
table_set_zoom(t, i), table_set_view(t, view) another step, the cursor's item brought into view; whether it changed
table_zoom_label(i), table_zoom_icon(i) a step's words in the language in use and its icon, for a program's control
table_zoom_key(i), table_zoom_from_key(key) a step's stable name, to save it, and back
table_card_name(name, width, lines) a name in at most lines lines of width pixels at the style's font: cut in its middle, its extension kept
table_card_icon_size(size) the font size of an icon in a card's picture size high (TABLE_CARD_ICON, half of it): the lead of a table without picture is built under it; a picture callback that falls back to an icon uses it too
table_band_cancel(t) Escape during a rectangle: the selection there was; false when none runs (a program that reads Escape before the table asks it first)

The keys in Grid: Left and Right move by a card, Up and Down by a row of cards, Page Up and Page Down by a page of rows; in Columns: Up and Down by a name, Left, Right, Page Up and Page Down by a column. Home and End go to the ends. Shift, Ctrl and Ctrl+Shift do what they do in a list (item_selection_move). table_keys, with the keyboard in a filter, moves by a row of cards or by a name; Left and Right stay the field's. Table_Events.zoomed says a zoom key or the wheel changed the step. Table.line_items is the cards in a row or the names in a column at the last build.

A program's own view of items uses the parts:

Procedure
item_move_target(key, at, n, per, flow, page) the item a key takes the cursor to among n items in lines (Item_Flow.Lines) or columns (.Columns) of per
item_band_update(band, sel, rows, box, layout, pressed_item, pressed_empty) after the items of box: a rectangle starts on a press on the empty part, selects the items it touches (Item_Band_Layout: rows of a virtual list, a grid of cards on one, columns), ends with the press
item_band_begin(band, box, sel, removing) Ctrl and a press on an item: a rectangle from there
item_band_cancel(band, sel, rows) Escape: the selection there was

The band leaves the rows that cannot be selected (Item_Rows.selectable) as they are, and never puts the cursor on one. A program that keeps a sum over the selection (bytes, a count by kind) sets Item_Band.changed and Item_Band.user once: changed(user, row, now_selected) is called for each row the band puts in or takes out of the selection, as it does, at the press (the selection there was cleared, without Ctrl), during the drag and at Escape. A table's band is Table.band.

Type to filter (src/ui/type_to_field.odin)

type_to_field(field) gives the keyboard to one field (a filter, a search box) when a printable character was typed in this build and no text field has the keyboard. The field takes the character in the same build. Called before the list, it takes the character from a list that has the keyboard; a field built after its list (a filter in a footer) needs the list's no_typeahead, else the list keeps the letters for its type-ahead. Call it in the build before the field is built; the field's key is its box's key from the build before.

if !dialog_open { ui.type_to_field(view.search_key) }
view.search_key = ui.line_edit("###search", &view.search, {placeholder = "Filter"}).box.key

typed_take(r) takes the character r out of the text typed in this build when it is its first character, so no field built after it gets it. True when it took it. The characters after it stay: "b r" typed in one build keeps its space. Use it for a key that is the program's while a field holds a given text: Space in an empty filter opens a preview, and the field never shows the space, not even for one frame.

if ui.focus_key() == view.search_key && ui.line_edit_string(&view.search) == "" && ui.typed_take(' ') { preview_toggle() }
view.search_key = ui.line_edit("###search", &view.search, {placeholder = "Filter"}).box.key

A tooltip per segment

segmented(id, labels, selected, tips) shows tips[i] when the pointer rests on segment i ("" or a missing entry: no tooltip). A screen reader reads it as the segment's description.

A segmented control's width

With no width given (next), a segmented control (look = .Pills) is segmented_width(labels) wide: every segment holds the widest label with its padding, in the style in effect, so a language's longer word widens the control instead of being cut. A width given is kept. A layout that must know the width before the control is built (to put it on a line of its own when the window is narrow) calls segmented_width itself:

fits := room - ui.segmented_width(labels[:]) >= search_least
ui.segmented("###filter", labels[:], &app.filter)   // segmented_width wide

Tests: tests/ui_robust (a_segmented_control_fits_its_labels).

Tests: tests/data_views (the table, type to filter, a segment's tooltip).

What a search found

A list filtered by what is typed lights the parts of each line that match: the theme's match colour (made readable on the tint) on its match_bg. Inside a selected row, where an accent tint disappears against the selection, match_runs and label_fuzzy drop the tint and underline the matched letters in the row's ink instead. The palette, a menu that searches, and a settings page's search do it; a program's own list too:

ranges := ui.word_ranges(line, query)        // each word (or "phrase") of the query, every place it is, in any case
_, ranges, _ = ui.fuzzy_words(query, line)   // or what a fuzzy search found
ui.next({width = ui.fill()})
ui.matched_label("###t", line, ranges)       // one line, cut with "…"; no ranges: a plain label
ui.match_runs(text, ranges, style, &runs)    // the same as runs, for a rich_paragraph of several lines

Sections, tiles, stacked bars, title strips

Pieces of a dense dashboard (sections.odin). hue(.Cyan) is a hue of the theme shown (Hue: accent, blue, purple, green, yellow, red, cyan, rose), for what a program colours by meaning.

ui.section_header("###mem", "Memory", ui.hue(.Cyan), "what the boot program left", "462 MiB")
ui.stacked_bar("###time", {{20.6, ui.hue(.Yellow), "20.6 ms"}, {33.2, ui.hue(.Blue), "33.2 ms"}})
if ui.flow({4, 4}) { for f, i in files { ui.tile(fmt.tprintf("###f%d", i), f, ui.hue(.Green)) } }
if ui.title_strip("###boot", "Boot") { open = false }
Procedure What it is
section_header(id, title, color, note, value, inline) a stripe of the colour, the title in capitals and bold in it, a weak note, a large value at the right; full width, or as wide as its words (inline: in a row with other things)
tile(id, text, color) a tile of the colour over what is under it, its words light; as wide as they are
stacked_bar(id, parts) a well cut in Bar_Parts (share, colour, words), the words of each in it when they fit; full width, 1.9 lines
title_strip(id, title) a title, white and bold, on the accent fading to the bar's colour; a red block closes (true)

In the machined and edged finishes a tile, a part and the strip are lit along their top and shaded along their bottom.

A stack of cards (src/ui/card_stack.odin)

A queue the person goes through one item at a time, each read whole (what they missed, what waits for a review): if ui.card_stack("###cards", &st, count, opts) { build the card st.at }. The card has the room left, and scrolls; under it a foot holds Previous, where the card is ("3 / 14"), the act in the middle (opts.settle, Acknowledge by default, in opts.settle_intent, Success by default) and Next. The Left and Right arrows and A do the same (opts.no_keys: a field in the card keeps them). After the stack, st.act says what was asked: .Previous and .Next moved st.at already; .Settle is the program's act on the card at st.at (an entry that stays in the list: the program moves st.at on). A card shown anew is shown from its top. With no card (count 0) nothing is built in it, and its buttons are off.

An empty view (src/ui/empty_state.odin)

ui.empty_state(id, {icon, title, note, actions}) is what a view shows when it has nothing to show: an empty folder, a filter that hides every row, a search with no result. It fills its parent and puts in its middle an icon in the weak colour, the title, the note (folded at EMPTY_STATE_NOTE_EM), and a button for each action. An action (ui.Empty_Action) is its words, a Lucide glyph and an intent, drawn as ui.button. It returns the index of the action clicked (-1: none): "Clear the filter", "Show hidden files", "New folder".