441 lines
17 KiB
Rust
441 lines
17 KiB
Rust
//! The first-start tour: a few pages explaining what QuickSearch indexes,
|
|
//! how results are ranked, and what the parts of the Search tab do.
|
|
//!
|
|
//! Shown once, to an installation that has never run before — `[ui]
|
|
//! tutorial_seen` is `Some(false)` only in a config file this version created,
|
|
//! so upgrading into this version does not summon it. The Help tab can bring
|
|
//! it back afterwards, which is also what keeps this from being write-only.
|
|
|
|
use crate::ui_util::{centered_modal, hint};
|
|
|
|
/// One page of the tour. Static text, so the pages are a table rather than a
|
|
/// match arm each.
|
|
struct Page {
|
|
title: &'static str,
|
|
/// Paragraphs. Rendered in order with a little space between them.
|
|
body: &'static [&'static str],
|
|
/// Rendered small and de-emphasised under the body — where to go, rather
|
|
/// than what the thing is.
|
|
pointer: Option<&'static str>,
|
|
}
|
|
|
|
const PAGES: &[Page] = &[
|
|
Page {
|
|
title: "Welcome to QuickSearch",
|
|
body: &[
|
|
"QuickSearch keeps an index of the folders you choose, and searches \
|
|
as you type.",
|
|
"By default only your user folder is indexed and searchable.",
|
|
"Because the answers come from the index rather than from reading \
|
|
your disk, results appear as fast as you can type, even across \
|
|
hundreds of thousands of files.",
|
|
],
|
|
pointer: Some("A quick tutorial for new users! Hit Skip to Exit."),
|
|
},
|
|
Page {
|
|
title: "What is indexed",
|
|
body: &[
|
|
"Indexing is QuickSearch reading through your folders once and \
|
|
remembering what it found, so that searching later is instant. It \
|
|
runs on its own in the background and keeps up with changes as you \
|
|
make them.",
|
|
"QuickSearch never connects to the internet, and always respects your privacy. \
|
|
QuickSearch can encrypt your index to make this remembered data more secure.",
|
|
"These are the folders being indexed right now:",
|
|
],
|
|
pointer: Some(
|
|
"To index more locations, open the Manage Index tab and add a folder. \
|
|
To set an index password, look near the bottom of the Settings tab.",
|
|
),
|
|
},
|
|
Page {
|
|
title: "How results are ranked",
|
|
body: &[
|
|
"The best search matches come first (have the lowest rank). \
|
|
Exact file-name matchs are best, then names that contain what you typed; then \
|
|
files whose contents contain the search terms, the ones mentioning it most often \
|
|
first; and last, files matched only by their full folder path.",
|
|
"The coloured number in the Rank column is which of those tiers a \
|
|
result came from: blue is a great match, red is a distant one. \
|
|
Clicking a column heading sorts by something else instead.",
|
|
],
|
|
pointer: Some("Right-click any column heading to choose which columns are shown."),
|
|
},
|
|
Page {
|
|
title: "The status bar",
|
|
body: &[
|
|
"The line along the bottom of the window is what QuickSearch is \
|
|
doing. While it is indexing it shows the phase, how far through it \
|
|
is, and how fast; when it has nothing to do it shows how many files \
|
|
are indexed.",
|
|
"Searching works the whole time, including during that first indexing run, \
|
|
but some files might not be shown in the results until the scan completes.",
|
|
],
|
|
pointer: None,
|
|
},
|
|
Page {
|
|
title: "Typos, and what a result can do",
|
|
body: &[
|
|
"Tick \"Fuzzy\"beside the search box to also match words with typos \
|
|
in them — \"repot\" will find \"report\". It searches more \
|
|
thoroughly, so it is a little slower; leave it off until you need \
|
|
it.",
|
|
"Right-click any result for more: open it, open the folder holding \
|
|
it, copy its path, or build a filter that hides files like it from \
|
|
future searches.",
|
|
],
|
|
pointer: Some(
|
|
"The ? button left of the search box lists the filters you can type \
|
|
into a query, like type:Document or modified:>=2024-01-01.",
|
|
),
|
|
},
|
|
Page {
|
|
title: "Duplicates",
|
|
body: &[
|
|
"The Duplicates tab looks for files across all indexed folders for identical copies. \
|
|
They are shown grouped together, with the largest wasted space first.",
|
|
"It is a quick way to find the same download sitting in three \
|
|
places. QuickSearch only shows you the groups; deleting anything is \
|
|
left to you.",
|
|
],
|
|
pointer: Some(
|
|
"For speed, files are compared by size and by how they begin (first 8KB). \
|
|
This is not a guarantee of an exact match. You can right click a result to verify before you delete anything.",
|
|
),
|
|
},
|
|
Page {
|
|
title: "Settings",
|
|
body: &[
|
|
"The Settings tab, at the right-hand end of the tab strip, is where \
|
|
you can tweak and tune the software. Mouse over any of \
|
|
the settings for a brief description of what they do.",
|
|
"Most changes wait for the Apply & Save button at the bottom.",
|
|
"QuickSearch is completely free for anyone to use. If you love it, please let your friends know about us!",
|
|
],
|
|
pointer: None,
|
|
},
|
|
];
|
|
|
|
/// The open tour.
|
|
pub struct Tutorial {
|
|
page: usize,
|
|
}
|
|
|
|
impl Tutorial {
|
|
pub fn new() -> Tutorial {
|
|
Tutorial { page: 0 }
|
|
}
|
|
|
|
/// Render. `roots` is the live indexed-folder list, named on the page
|
|
/// about indexing so the tour describes this installation rather than a
|
|
/// generic one.
|
|
/// Returns true once the tour is finished with — skipped or read to the
|
|
/// end — which is the caller's cue to remember that and drop it.
|
|
pub fn ui(&mut self, ctx: &egui::Context, roots: &[String]) -> bool {
|
|
let page = &PAGES[self.page.min(PAGES.len() - 1)];
|
|
let (first, last) = (self.page == 0, self.page + 1 == PAGES.len());
|
|
let mut dismissed = false;
|
|
let mut step: i64 = 0;
|
|
|
|
centered_modal(ctx, page.title, |ui| {
|
|
ui.set_max_width(520.0);
|
|
for paragraph in page.body {
|
|
ui.label(*paragraph);
|
|
ui.add_space(6.0);
|
|
}
|
|
// The one page that shows live state rather than static text.
|
|
if self.page == 1 {
|
|
if roots.is_empty() {
|
|
ui.label(hint("No folders are indexed yet."));
|
|
} else {
|
|
for root in roots {
|
|
ui.monospace(root);
|
|
}
|
|
}
|
|
ui.add_space(6.0);
|
|
}
|
|
if let Some(pointer) = page.pointer {
|
|
ui.label(hint(pointer));
|
|
}
|
|
|
|
ui.add_space(10.0);
|
|
ui.separator();
|
|
// Three equal thirds rather than one row: it is the only layout
|
|
// that puts Skip in the middle without measuring the buttons
|
|
// either side of it, whose widths change with the page ("Next"
|
|
// becoming "Finish") and with the counter's digits.
|
|
ui.columns(3, |cols| {
|
|
// A column lays its contents out *justified*, so a button put
|
|
// straight into one is stretched to the full third. The other
|
|
// two escape that by nesting their own layout; this one has to
|
|
// say so.
|
|
cols[0].with_layout(egui::Layout::left_to_right(egui::Align::Min), |ui| {
|
|
if ui.add_enabled(!first, egui::Button::new("Back")).clicked() {
|
|
step = -1;
|
|
}
|
|
});
|
|
cols[1].vertical_centered(|ui| {
|
|
if ui.button("Skip").clicked() {
|
|
dismissed = true;
|
|
}
|
|
});
|
|
// `Align::Min`, not `Center`: a column is as tall as the rest
|
|
// of the window, so centring in it drops the button a hundred
|
|
// points below the two beside it.
|
|
cols[2].with_layout(egui::Layout::right_to_left(egui::Align::Min), |ui| {
|
|
let p = crate::color::palette(ui.visuals().dark_mode);
|
|
let next = if last { "Finish" } else { "Next" };
|
|
if ui
|
|
.add(crate::ui_util::bordered_button(next, p.blue))
|
|
.clicked()
|
|
{
|
|
if last {
|
|
dismissed = true;
|
|
} else {
|
|
step = 1;
|
|
}
|
|
}
|
|
ui.label(hint(format!("{} of {}", self.page + 1, PAGES.len())));
|
|
});
|
|
});
|
|
});
|
|
|
|
// Applied after the closure so the page a frame rendered stays the page
|
|
// its buttons were laid out for.
|
|
if step != 0 {
|
|
let next = self.page as i64 + step;
|
|
self.page = next.clamp(0, PAGES.len() as i64 - 1) as usize;
|
|
}
|
|
dismissed
|
|
}
|
|
}
|
|
|
|
#[cfg(test)]
|
|
mod tests {
|
|
use super::*;
|
|
use crate::test_ui::{click_at, painted_text, raw_input};
|
|
|
|
const SCREEN: egui::Vec2 = egui::vec2(1000.0, 700.0);
|
|
|
|
/// Two passes: an `egui::Window` is measured on its first frame and only
|
|
/// placed on the next, so a single pass paints nothing to read back and
|
|
/// has nothing at a known position to click.
|
|
fn frame(
|
|
ctx: &egui::Context,
|
|
tour: &mut Tutorial,
|
|
events: Vec<egui::Event>,
|
|
) -> (egui::FullOutput, bool) {
|
|
let roots = ["/home/me".to_string()];
|
|
let _ = ctx.run(raw_input(SCREEN, Vec::new()), |ctx| {
|
|
tour.ui(ctx, &roots);
|
|
});
|
|
let mut dismissed = false;
|
|
let out = ctx.run(raw_input(SCREEN, events), |ctx| {
|
|
dismissed = tour.ui(ctx, &roots);
|
|
});
|
|
(out, dismissed)
|
|
}
|
|
|
|
/// Every page has something to say, and says it.
|
|
#[test]
|
|
fn every_page_paints_its_own_title_and_body() {
|
|
for (page, spec) in PAGES.iter().enumerate() {
|
|
let ctx = crate::test_ui::ctx();
|
|
let mut tour = Tutorial { page };
|
|
let (out, _) = frame(&ctx, &mut tour, Vec::new());
|
|
let painted = painted_text(&out);
|
|
assert!(
|
|
painted.iter().any(|t| t == spec.title),
|
|
"page {page} painted no title: {painted:?}"
|
|
);
|
|
assert!(!spec.body.is_empty(), "page {page} has an empty body");
|
|
assert!(
|
|
painted
|
|
.iter()
|
|
.any(|t| t == &format!("{} of {}", page + 1, PAGES.len())),
|
|
"page {page} did not say where it is: {painted:?}"
|
|
);
|
|
}
|
|
}
|
|
|
|
/// The page about indexing names *this* installation's folders, not a
|
|
/// generic example.
|
|
#[test]
|
|
fn the_indexing_page_lists_the_configured_folders() {
|
|
let ctx = crate::test_ui::ctx();
|
|
let mut tour = Tutorial { page: 1 };
|
|
let roots = ["/srv/projects".to_string()];
|
|
let _ = ctx.run(raw_input(SCREEN, Vec::new()), |ctx| {
|
|
tour.ui(ctx, &roots);
|
|
});
|
|
let out = ctx.run(raw_input(SCREEN, Vec::new()), |ctx| {
|
|
tour.ui(ctx, &roots);
|
|
});
|
|
let painted = painted_text(&out);
|
|
assert!(painted.iter().any(|t| t == "/srv/projects"), "{painted:?}");
|
|
}
|
|
|
|
/// The y of the footer row on `page`, found by walking down the middle
|
|
/// column, which only Skip occupies. Wrapped text height moves the row
|
|
/// from page to page, so it is probed rather than guessed.
|
|
fn footer_y(ctx: &egui::Context, page: usize) -> f32 {
|
|
for y in (150..600).step_by(2) {
|
|
let mut t = Tutorial { page };
|
|
let (_, dismissed) = frame(ctx, &mut t, click_at(egui::pos2(500.0, y as f32)));
|
|
if dismissed {
|
|
return y as f32;
|
|
}
|
|
}
|
|
panic!("no Skip button down the middle of page {page}");
|
|
}
|
|
|
|
/// The stretch of x along the footer row that one button answers a click
|
|
/// on — where it is, and how wide.
|
|
#[derive(Debug, Clone, Copy)]
|
|
struct Span {
|
|
lo: f32,
|
|
hi: f32,
|
|
}
|
|
|
|
impl Span {
|
|
fn width(&self) -> f32 {
|
|
self.hi - self.lo
|
|
}
|
|
}
|
|
|
|
/// The three footer buttons, found by what clicking each one does: Back
|
|
/// steps a page back, Next steps one forward, Skip dismisses.
|
|
///
|
|
/// Must be run on a middle page — on the last page Finish and Skip both
|
|
/// dismiss without moving, and on the first Back is disabled.
|
|
fn footer_spans(ctx: &egui::Context, page: usize) -> [Option<Span>; 3] {
|
|
assert!(page > 0 && page + 1 < PAGES.len(), "probe a middle page");
|
|
let y = footer_y(ctx, page);
|
|
let mut spans: [Option<Span>; 3] = [None; 3];
|
|
for x in 150..850 {
|
|
let mut t = Tutorial { page };
|
|
let (_, dismissed) = frame(ctx, &mut t, click_at(egui::pos2(x as f32, y)));
|
|
let x = x as f32;
|
|
let which = if dismissed {
|
|
1 // Skip
|
|
} else if t.page + 1 == page {
|
|
0 // Back
|
|
} else if t.page == page + 1 {
|
|
2 // Next
|
|
} else {
|
|
continue;
|
|
};
|
|
match &mut spans[which] {
|
|
Some(span) => span.hi = x,
|
|
slot => *slot = Some(Span { lo: x, hi: x }),
|
|
}
|
|
}
|
|
spans
|
|
}
|
|
|
|
/// The footer reads Back, then Skip, then Next — and each does what its
|
|
/// label says. Positions are probed rather than asserted against numbers:
|
|
/// the window auto-sizes to the page's text, so the thirds move.
|
|
///
|
|
/// The widths are the other half of it. `Ui::columns` lays a column out
|
|
/// justified, so a button dropped straight into one comes out as wide as
|
|
/// the whole third — which is what Back was until it was given a layout of
|
|
/// its own. Two buttons with four-letter labels either side of the row
|
|
/// have to come out the same size.
|
|
#[test]
|
|
fn the_footer_runs_back_then_skip_then_next_at_the_same_size() {
|
|
let ctx = crate::test_ui::ctx();
|
|
let [back, skip, next] = footer_spans(&ctx, 1);
|
|
let back = back.expect("no Back button in the footer");
|
|
let skip = skip.expect("no Skip button in the footer");
|
|
let next = next.expect("no Next button in the footer");
|
|
assert!(
|
|
back.lo < skip.lo,
|
|
"Back ({back:?}) is not left of Skip ({skip:?})"
|
|
);
|
|
assert!(
|
|
skip.lo < next.lo,
|
|
"Skip ({skip:?}) is not left of Next ({next:?})"
|
|
);
|
|
|
|
assert!(
|
|
(back.width() - next.width()).abs() <= 2.0,
|
|
"Back is {} wide against Next's {}",
|
|
back.width(),
|
|
next.width()
|
|
);
|
|
// Belt and braces on the shape of the bug: a stretched button fills
|
|
// its third of a 520-point modal, which no four-letter label does.
|
|
assert!(
|
|
back.width() < 80.0,
|
|
"Back is stretched to {} points",
|
|
back.width()
|
|
);
|
|
}
|
|
|
|
/// Back is disabled on the first page, so nothing in the footer can walk
|
|
/// the tour off the front.
|
|
#[test]
|
|
fn the_first_page_cannot_go_back() {
|
|
let ctx = crate::test_ui::ctx();
|
|
let y = footer_y(&ctx, 0);
|
|
for x in (150..850).step_by(4) {
|
|
let mut t = Tutorial { page: 0 };
|
|
let _ = frame(&ctx, &mut t, click_at(egui::pos2(x as f32, y)));
|
|
assert!(
|
|
t.page == 0 || t.page == 1,
|
|
"clicking x={x} left page {}",
|
|
t.page
|
|
);
|
|
}
|
|
}
|
|
|
|
/// Clicking anywhere in the button row, on any page; collects what fired.
|
|
fn sweep(ctx: &egui::Context, tour: &mut Tutorial) -> Vec<usize> {
|
|
let mut seen = Vec::new();
|
|
for y in (200..500).step_by(4) {
|
|
for x in (240..760).step_by(8) {
|
|
let mut t = Tutorial { page: tour.page };
|
|
let (_, dismissed) = frame(ctx, &mut t, click_at(egui::pos2(x as f32, y as f32)));
|
|
if dismissed {
|
|
seen.push(t.page);
|
|
}
|
|
}
|
|
}
|
|
seen
|
|
}
|
|
|
|
/// Both ways out of the tour report the dismissal, so the flag gets set
|
|
/// whichever the user takes. Positions depend on wrapped text height, so
|
|
/// the button row is swept rather than guessed at — the same approach the
|
|
/// confirmation modals' tests take.
|
|
#[test]
|
|
fn skip_and_finish_both_dismiss() {
|
|
let ctx = crate::test_ui::ctx();
|
|
|
|
// Skip is on every page.
|
|
let mut tour = Tutorial { page: 0 };
|
|
assert!(
|
|
!sweep(&ctx, &mut tour).is_empty(),
|
|
"Skip never fired on the first page"
|
|
);
|
|
|
|
// Finish only on the last, where it replaces Next.
|
|
let mut tour = Tutorial {
|
|
page: PAGES.len() - 1,
|
|
};
|
|
assert!(
|
|
!sweep(&ctx, &mut tour).is_empty(),
|
|
"Finish never fired on the last page"
|
|
);
|
|
let ctx = crate::test_ui::ctx();
|
|
let mut tour = Tutorial {
|
|
page: PAGES.len() - 1,
|
|
};
|
|
let (out, _) = frame(&ctx, &mut tour, Vec::new());
|
|
assert!(
|
|
painted_text(&out).contains(&"Finish".to_string()),
|
|
"the last page still offers Next"
|
|
);
|
|
}
|
|
}
|