libsurfer/
help.rs

1//! Help texts and dialogs.
2use egui::{Context, Grid, OpenUrl, RichText, ScrollArea, Ui, Window};
3use egui_remixicon::icons;
4use emath::{Align2, Pos2};
5
6use crate::keyboard_shortcuts::{ShortcutAction, SurferShortcuts};
7use crate::wave_source::LoadOptions;
8use crate::{SystemState, message::Message};
9
10impl SystemState {
11    pub fn help_message(&self, ui: &mut Ui) {
12        if self.user.waves.is_none() {
13            let show_command_prompt = self
14                .user
15                .config
16                .shortcuts
17                .format_shortcut(ShortcutAction::ShowCommandPrompt);
18
19            ui.label(RichText::new(
20                "Drag and drop a VCD, FST, or GHW file here to open it",
21            ));
22
23            #[cfg(target_arch = "wasm32")]
24            ui.label(RichText::new(format!(
25                "Or press {show_command_prompt} and type load_url"
26            )));
27            #[cfg(not(target_arch = "wasm32"))]
28            ui.label(RichText::new(format!(
29                "Or press {show_command_prompt} and type load_file or load_url"
30            )));
31            #[cfg(target_arch = "wasm32")]
32            ui.label(RichText::new(
33                "Or use the file menu or toolbar to open a URL",
34            ));
35            #[cfg(not(target_arch = "wasm32"))]
36            ui.label(RichText::new(
37                "Or use the file menu or toolbar to open a file or a URL",
38            ));
39            ui.horizontal(|ui| {
40                ui.label(RichText::new("Or click"));
41                if ui.link("here").clicked() {
42                    self.channels
43                        .msg_sender
44                        .send(Message::LoadWaveformFileFromUrl(
45                            "https://app.surfer-project.org/picorv32.vcd".to_string(),
46                            LoadOptions::Clear,
47                        ))
48                        .ok();
49                }
50                ui.label("to open an example waveform");
51            });
52
53            #[cfg(not(test))]
54            if !self.file_history.files().is_empty() {
55                ui.add_space(10.0);
56                ui.label(RichText::new("Recent files"));
57
58                let labels = self.file_history.display_labels();
59                for (path, label) in self.file_history.files().iter().zip(labels.iter()) {
60                    if ui.link(label).on_hover_text(path.as_str()).clicked() {
61                        self.channels
62                            .msg_sender
63                            .send(Message::LoadFile(path.clone(), LoadOptions::Clear))
64                            .ok();
65                    }
66                }
67            }
68
69            ui.add_space(20.0);
70            ui.separator();
71            ui.add_space(20.0);
72        }
73
74        controls_listing(ui, &self.user.config.shortcuts);
75
76        ui.add_space(20.0);
77        ui.separator();
78        ui.add_space(20.0);
79
80        #[cfg(target_arch = "wasm32")]
81        {
82            ui.label(RichText::new(
83            "Note that this web based version is a bit slower than a natively installed version. There may also be a long delay with unresponsiveness when loading large waveforms because the web assembly version does not currently support multi threading.",
84        ));
85
86            ui.hyperlink_to(
87                "See https://gitlab.com/surfer-project/surfer for install instructions",
88                "https://gitlab.com/surfer-project/surfer",
89            );
90        }
91    }
92}
93
94pub fn draw_about_window(ctx: &Context, msgs: &mut Vec<Message>) {
95    let mut open = true;
96    Window::new("About Surfer")
97        .open(&mut open)
98        .collapsible(false)
99        .resizable(true)
100        .show(ctx, |ui| {
101            ui.vertical_centered(|ui| {
102                ui.label(RichText::new("🏄 Surfer").monospace().size(24.));
103                ui.add_space(20.);
104                ui.label(format!(
105                    "Cargo version: {ver}",
106                    ver = env!("CARGO_PKG_VERSION")
107                ));
108                if ui
109                    .small_button(format!(
110                        "Git version: {ver}",
111                        ver = env!("VERGEN_GIT_DESCRIBE")
112                    ))
113                    .on_hover_text("Click to copy git version")
114                    .clicked()
115                {
116                    ctx.copy_text(env!("VERGEN_GIT_DESCRIBE").to_string());
117                }
118                ui.label(format!(
119                    "Build date: {date}",
120                    date = env!("VERGEN_BUILD_DATE")
121                ));
122                ui.hyperlink_to(
123                    (icons::GITLAB_FILL).to_string() + " repository",
124                    "https://gitlab.com/surfer-project/surfer",
125                );
126                ui.hyperlink_to("Homepage", "https://surfer-project.org/");
127                ui.add_space(10.);
128                if ui.button("Close").clicked() {
129                    msgs.push(Message::SetAboutVisible(false));
130                }
131            })
132        });
133    if !open {
134        msgs.push(Message::SetAboutVisible(false));
135    }
136}
137
138pub fn draw_quickstart_help_window(
139    ctx: &Context,
140    msgs: &mut Vec<Message>,
141    shortcuts: &SurferShortcuts,
142) {
143    let mut open = true;
144    let show_command_prompt = shortcuts.format_shortcut(ShortcutAction::ShowCommandPrompt);
145    Window::new("🏄 Surfer quick start")
146        .collapsible(true)
147        .resizable(true)
148        .pivot(Align2::CENTER_CENTER)
149        .open(&mut open)
150        .default_pos(Pos2::new(
151            ctx.content_rect().size().x / 2.,
152            ctx.content_rect().size().y / 2.,
153        ))
154        .show(ctx, |ui| {
155            ui.vertical(|ui| {
156                ui.add_space(5.);
157
158                ui.label(RichText::new("Controls").size(20.));
159                ui.add_space(5.);
160                ui.label("↔ Use scroll and ctrl+scroll to navigate the waveform");
161                ui.label(format!(
162                    "🚀 Press {show_command_prompt} to open the command palette"
163                ));
164                ui.label("✋ Click the middle mouse button for gestures");
165                ui.label("❓ See the help menu for more controls");
166                ui.add_space(10.);
167                ui.label(RichText::new("Adding traces").size(20.));
168                ui.add_space(5.);
169                ui.label("Add more traces using the command palette or using the sidebar");
170                ui.add_space(10.);
171                ui.label(RichText::new("Opening files").size(20.));
172                ui.add_space(5.);
173                ui.label("Open a new file by");
174                ui.label("- dragging a VCD, FST, or GHW file");
175                #[cfg(target_arch = "wasm32")]
176                ui.label("- typing load_url in the command palette");
177                #[cfg(not(target_arch = "wasm32"))]
178                ui.label("- typing load_url or load_file in the command palette");
179                ui.label("- using the file menu");
180                ui.label("- using the toolbar");
181                ui.add_space(10.);
182            });
183            ui.vertical_centered(|ui| {
184                if ui.button("Close").clicked() {
185                    msgs.push(Message::SetQuickStartVisible(false));
186                }
187            })
188        });
189    if !open {
190        msgs.push(Message::SetQuickStartVisible(false));
191    }
192}
193
194pub fn draw_control_help_window(
195    ctx: &Context,
196    msgs: &mut Vec<Message>,
197    shortcuts: &SurferShortcuts,
198) {
199    let mut open = true;
200    Window::new("🖮 Surfer controls")
201        .collapsible(true)
202        .resizable(true)
203        .open(&mut open)
204        .show(ctx, |ui| {
205            ui.vertical_centered(|ui| {
206                key_listing(ui, shortcuts);
207                ui.add_space(10.);
208                if ui.button("Close").clicked() {
209                    msgs.push(Message::SetKeyHelpVisible(false));
210                }
211            });
212        });
213    if !open {
214        msgs.push(Message::SetKeyHelpVisible(false));
215    }
216}
217
218/// Long list of key binding for the dialog.
219fn key_listing(ui: &mut Ui, shortcuts: &SurferShortcuts) {
220    let save_state_file = shortcuts.format_shortcut(ShortcutAction::SaveStateFile);
221    let toggle_hierarchy = shortcuts.format_shortcut(ShortcutAction::ToggleSidePanel);
222    let toggle_toolbar = shortcuts.format_shortcut(ShortcutAction::ToggleToolbar);
223    let reload_waveform = shortcuts.format_shortcut(ShortcutAction::ReloadWaveform);
224    let focus_item = shortcuts.format_shortcut(ShortcutAction::ItemFocus);
225    let goto_end = shortcuts.format_shortcut(ShortcutAction::GoToEnd);
226    let goto_start = shortcuts.format_shortcut(ShortcutAction::GoToStart);
227    let zoom_in = shortcuts.format_shortcut(ShortcutAction::ZoomIn);
228    let zoom_out = shortcuts.format_shortcut(ShortcutAction::ZoomOut);
229    let show_command_prompt = shortcuts.format_shortcut(ShortcutAction::ShowCommandPrompt);
230    let selected_item_toggle = shortcuts.format_shortcut(ShortcutAction::SelectToggle);
231    let undo = shortcuts.format_shortcut(ShortcutAction::Undo);
232    let redo = shortcuts.format_shortcut(ShortcutAction::Redo);
233    let add_marker = shortcuts.format_shortcut(ShortcutAction::MarkerAdd);
234    let scroll_up = shortcuts.format_shortcut(ShortcutAction::ScrollUp);
235    let scroll_down = shortcuts.format_shortcut(ShortcutAction::ScrollDown);
236    let delete_selected = shortcuts.format_shortcut(ShortcutAction::DeleteSelected);
237    let toggle_menu = shortcuts.format_shortcut(ShortcutAction::ToggleMenu);
238    let divider_add = shortcuts.format_shortcut(ShortcutAction::DividerAdd);
239    #[cfg(not(target_arch = "wasm32"))]
240    let ui_zoom_in = shortcuts.format_shortcut(ShortcutAction::UiZoomIn);
241    #[cfg(not(target_arch = "wasm32"))]
242    let ui_zoom_out = shortcuts.format_shortcut(ShortcutAction::UiZoomOut);
243    let keys = vec![
244        ("🚀", show_command_prompt.as_str(), "Show command prompt"),
245        ("↔", "Scroll", "Pan"),
246        ("🔎", "Ctrl+Scroll", "Zoom"),
247        (icons::SAVE_FILL, &save_state_file, "Save the state"),
248        (
249            icons::LAYOUT_LEFT_FILL,
250            &toggle_hierarchy,
251            "Show or hide the design hierarchy",
252        ),
253        (icons::MENU_FILL, &toggle_menu, "Show or hide menu"),
254        (icons::TOOLS_FILL, &toggle_toolbar, "Show or hide toolbar"),
255        (icons::ZOOM_IN_FILL, &zoom_in, "Zoom in"),
256        (icons::ZOOM_OUT_FILL, &zoom_out, "Zoom out"),
257        #[cfg(not(target_arch = "wasm32"))]
258        ("", &ui_zoom_in, "UI Zoom in"),
259        #[cfg(not(target_arch = "wasm32"))]
260        ("", &ui_zoom_out, "UI Zoom out"),
261        ("", "k/⬆", "Scroll up"),
262        ("", "j/⬇", "Scroll down"),
263        ("", "Ctrl+k/⬆", "Move focused item up"),
264        ("", "Ctrl+j/⬇", "Move focused item down"),
265        ("", "Alt+k/⬆", "Move focus up"),
266        ("", "Alt+j/⬇", "Move focus down"),
267        ("", &selected_item_toggle, "Add focused item to selection"),
268        ("", "Ctrl+Alt+k/⬆", "Extend selection up"),
269        ("", "Ctrl+Alt+j/⬇", "Extend selection down"),
270        ("", &undo, "Undo last change"),
271        ("", &redo, "Redo last change"),
272        ("", &focus_item, "Fast focus a variable"),
273        ("", &add_marker, "Add marker at current cursor"),
274        ("", "Ctrl+0-9", "Add numbered marker"),
275        ("", "0-9", "Center view at numbered marker"),
276        ("", &divider_add, "Add divider"),
277        (icons::REWIND_START_FILL, &goto_start, "Go to start"),
278        (icons::FORWARD_END_FILL, &goto_end, "Go to end"),
279        (icons::REFRESH_LINE, &reload_waveform, "Reload waveform"),
280        (icons::SPEED_FILL, &scroll_up, "Go one page/screen right"),
281        (icons::REWIND_FILL, &scroll_down, "Go one page/screen left"),
282        (
283            icons::PLAY_FILL,
284            "➡/l",
285            "Go to next transition of focused variable (changeable in config)",
286        ),
287        (
288            icons::PLAY_REVERSE_FILL,
289            "⬅/h",
290            "Go to previous transition of focused variable (changeable in config)",
291        ),
292        (
293            "",
294            "Ctrl+➡/l",
295            "Go to next non-zero transition of focused variable",
296        ),
297        (
298            "",
299            "Ctrl+⬅/h",
300            "Go to previous non-zero transition of focused variable",
301        ),
302        (
303            icons::DELETE_BIN_2_FILL,
304            &delete_selected,
305            "Delete focused item",
306        ),
307        #[cfg(not(target_arch = "wasm32"))]
308        (icons::FULLSCREEN_LINE, "F11", "Toggle full screen"),
309    ];
310
311    Grid::new("keys")
312        .num_columns(3)
313        .spacing([5., 5.])
314        .show(ui, |ui| {
315            for (symbol, control, description) in keys {
316                let control = ctrl_to_cmd(control);
317                ui.label(symbol);
318                ui.label(control);
319                ui.label(description);
320                ui.end_row();
321            }
322        });
323
324    add_hint_text(ui);
325}
326
327/// Shorter list displayed at startup screen.
328fn controls_listing(ui: &mut Ui, shortcuts: &SurferShortcuts) {
329    let show_command_prompt = shortcuts.format_shortcut(ShortcutAction::ShowCommandPrompt);
330    let toggle_hierarchy = shortcuts.format_shortcut(ShortcutAction::ToggleSidePanel);
331    let toggle_toolbar = shortcuts.format_shortcut(ShortcutAction::ToggleToolbar);
332    let toggle_menu = shortcuts.format_shortcut(ShortcutAction::ToggleMenu);
333
334    let controls = vec![
335        ("🚀", show_command_prompt.as_str(), "Show command prompt"),
336        ("↔", "Horizontal Scroll", "Pan"),
337        ("↕", "j, k, Up, Down", "Scroll down/up"),
338        ("⌖", "Ctrl+j, k, Up, Down", "Move focus down/up"),
339        ("🔃", "Alt+j, k, Up, Down", "Move focused item down/up"),
340        ("🔎", "Ctrl+Scroll", "Zoom"),
341        (
342            icons::LAYOUT_LEFT_2_FILL,
343            &toggle_hierarchy,
344            "Show or hide the design hierarchy",
345        ),
346        (icons::MENU_FILL, &toggle_menu, "Show or hide menu"),
347        (icons::TOOLS_FILL, &toggle_toolbar, "Show or hide toolbar"),
348    ];
349
350    Grid::new("controls")
351        .num_columns(2)
352        .spacing([20., 5.])
353        .show(ui, |ui| {
354            for (symbol, control, description) in controls {
355                let control = ctrl_to_cmd(control);
356                ui.label(format!("{symbol}  {control}"));
357                ui.label(description);
358                ui.end_row();
359            }
360        });
361    add_hint_text(ui);
362}
363
364fn add_hint_text(ui: &mut Ui) {
365    ui.add_space(20.);
366    ui.label(RichText::new("Hint: You can repeat keybinds by typing Alt+0-9 before them. For example, Alt+1 Alt+0 k scrolls 10 steps up."));
367}
368
369// Display information about licenses for Surfer and used crates.
370pub fn draw_license_window(ctx: &Context, msgs: &mut Vec<Message>) {
371    let mut open = true;
372    let text = include_str!("../../LICENSE-EUPL-1.2.txt");
373    Window::new("Surfer License")
374        .open(&mut open)
375        .collapsible(false)
376        .max_height(600.)
377        .default_size((600., 600.))
378        .show(ctx, |ui| {
379            ScrollArea::vertical().show(ui, |ui| {
380                ui.label(text);
381            });
382            ui.add_space(10.);
383            ui.horizontal(|ui| {
384                if ui.button("Dependency licenses").clicked() {
385                    ctx.open_url(OpenUrl {
386                        url: "https://docs.surfer-project.org/licenses.html".to_string(),
387                        new_tab: true,
388                    });
389                }
390                if ui.button("Close").clicked() {
391                    msgs.push(Message::SetLicenseVisible(false));
392                }
393            });
394        });
395    if !open {
396        msgs.push(Message::SetLicenseVisible(false));
397    }
398}
399
400// Replace Ctrl with Cmd in case of macos, unless we are running tests
401fn ctrl_to_cmd(instr: &str) -> String {
402    #[cfg(all(target_os = "macos", not(test)))]
403    let instring = instr.to_string().replace("Ctrl", "Cmd");
404    #[cfg(any(not(target_os = "macos"), test))]
405    let instring = instr.to_string();
406    instring
407}
libsurfer/help.rs

libsurfer/
help.rs
