#1256 Docs: Add screenshots of parts

doc/realearn/antora.yml

@@ -1,5 +1,5 @@
 name: realearn
-title: ReaLearn
+title: ReaLearn Reference
 version: ~
 nav:
   - modules/ROOT/nav.adoc

doc/realearn/modules/ROOT/pages/user-interface/main-panel.adoc

@@ -2,7 +2,7 @@
 
 The main panel is what you see immediately when you open the Helgobox plug-in window.
 
-image:realearn/screenshots/main-panel.png[Main panel]
+image:realearn/screenshots/main-panel.png[Screenshot]
 
 It's divided into 3 larger areas:
 

doc/realearn/modules/ROOT/pages/user-interface/main-panel/bottom-area.adoc

@@ -1,6 +1,8 @@
 
 = Bottom area
 
+image:realearn/screenshots/main-panel-bottom.png[Screenshot]
+
 == Unit menu
 
 Press the button will reveal a menu with the following actions to manage xref:key-concepts.adoc#unit[Units]:

doc/realearn/modules/ROOT/pages/user-interface/main-panel/inputoutput-section.adoc

@@ -1,6 +1,8 @@
 
 = Input/output section
 
+image:realearn/screenshots/main-panel-input-output.png[Screenshot]
+
 This section is essential to connect ReaLearn to a specific controller.
 
 Also see xref:best-practices.adoc#best-practices-input-output[].

doc/realearn/modules/ROOT/pages/user-interface/main-panel/let-through-checkboxes.adoc

@@ -1,6 +1,8 @@
 [[let-through-checkboxes]]
 = Let through checkboxes
 
+image:realearn/screenshots/main-panel-let-through-checkboxes.png[Screenshot]
+
 See xref:further-concepts/unit-concepts.adoc#letting-through-events[].
 
 Matched:: If checked, even events matched by at least one mapping are let through.

doc/realearn/modules/ROOT/pages/user-interface/main-panel/mapping-group-section.adoc

@@ -1,5 +1,7 @@
 = Mapping group section
 
+image:realearn/screenshots/main-panel-group.png[Screenshot]
+
 [[mapping-group-menu]]
 == Group menu
 

doc/realearn/modules/ROOT/pages/user-interface/main-panel/mapping-row.adoc

@@ -1,6 +1,8 @@
 
 = Mapping row
 
+image:realearn/screenshots/main-panel-mapping-row.png[Screenshot]
+
 Each mapping row represents one ReaLearn mapping.
 
 The mapping, source and target labels of a mapping row are greyed out whenever the mapping is _off_.

doc/realearn/modules/ROOT/pages/user-interface/main-panel/mappings-toolbar.adoc

@@ -1,6 +1,8 @@
 
 = Mappings toolbar
 
+image:realearn/screenshots/main-panel-mapping-toolbar.png[Screenshot]
+
 [[add-one-button]]
 == Add one button
 

doc/realearn/modules/ROOT/pages/user-interface/main-panel/menu-bar.adoc

@@ -1,6 +1,7 @@
-
 = Menu bar
 
+image:realearn/screenshots/main-panel-menu-bar.png[Screenshot]
+
 == Menu button
 
 This opens the main menu of Helgobox/ReaLearn.

doc/realearn/modules/ROOT/pages/user-interface/main-panel/notes-button.adoc

@@ -1,5 +1,7 @@
 
 = Notes button
 
+image:realearn/screenshots/main-panel-notes-button.png[Screenshot]
+
 Allows you to save custom notes/comments for the current compartment.
 These notes are also included in compartment presets.

doc/realearn/modules/ROOT/pages/user-interface/main-panel/preset-section.adoc

@@ -1,6 +1,8 @@
 
 = Preset section
 
+image:realearn/screenshots/main-panel-preset.png[Screenshot]
+
 == Preset menu
 
 This menu makes it possible to load compartment presets for the currently shown compartment.

doc/realearn/modules/ROOT/pages/user-interface/main-panel/show-buttons.adoc

@@ -1,5 +1,6 @@
-
 = Show buttons
 
+image:realearn/screenshots/main-panel-show-buttons.png[Screenshot]
+
 This lets you choose which mapping compartment is displayed.
 See xref:key-concepts.adoc#compartment[].

doc/realearn/modules/ROOT/pages/user-interface/mapping-panel.adoc

@@ -3,4 +3,4 @@
 
 When you press the _Edit_ button of a mapping row, the _mapping panel_ appears, which lets you look at the corresponding mapping in detail and modify it:
 
-image:realearn/screenshots/mapping-panel.png[Mapping panel]
+image:realearn/screenshots/mapping-panel.png[Screenshot]

doc/realearn/modules/ROOT/pages/user-interface/mapping-panel/bottom-section.adoc

@@ -1,10 +1,12 @@
-
 = Bottom section
 
-The section at the bottom has two functions:
+image:realearn/screenshots/mapping-panel-bottom.png[Screenshot]
+
+The section at the bottom has the following functions:
 
 - To provide context-sensitive help for the glue section
 - To provide control information, feedback information and error reporting
+- To provide navigation and general mapping control
 
 == Help
 
@@ -27,4 +29,16 @@ NOTE: If the target supports MIDI real-time control and the source is a MIDI sou
 
 The right text area shows information about which feedback values are sent from the glue section to the source.
 
-[split=1]
+== Beep on success checkbox
+
+Makes the mapping play a sound whenever the target has been invoked successfully.
+Nice for trigger-like targets such as xref:target-types/realearn-targets/realearn-take-mapping-snapshot.adoc#realearn-take-mapping-snapshot[] for which there's no other good way to know if it worked.
+
+== Previous/next buttons
+
+Allows you to jump to the previous or next mapping.
+Considers only mappings that are currently visible in the mapping rows panel.
+
+== Enabled checkbox
+
+Enables or disables the mapping as a whole.

doc/realearn/modules/ROOT/pages/user-interface/mapping-panel/general-section.adoc

@@ -1,6 +1,8 @@
 
 = General section
 
+image:realearn/screenshots/mapping-panel-general.png[Screenshot]
+
 This section provides the following mapping-related elements.
 
 == Name field
@@ -69,17 +71,3 @@ xref:user-interface/mapping-panel/advanced-settings-dialog.adoc#advanced-setting
 == Find in mapping list button
 
 Scrolls the mapping rows panel so that the corresponding mapping row for this mapping gets visible.
-
-== Beep on success checkbox
-
-Makes the mapping play a sound whenever the target has been invoked successfully.
-Nice for trigger-like targets such as xref:target-types/realearn-targets/realearn-take-mapping-snapshot.adoc#realearn-take-mapping-snapshot[] for which there's no other good way to know if it worked.
-
-== Previous/next buttons
-
-Allows you to jump to the previous or next mapping.
-Considers only mappings that are currently visible in the mapping rows panel.
-
-== Enabled checkbox
-
-Enables or disables the mapping as a whole.

doc/realearn/modules/ROOT/pages/user-interface/mapping-panel/glue-section.adoc

@@ -1,6 +1,8 @@
 [#glue-section]
 = Glue section
 
+image:realearn/screenshots/mapping-panel-glue.png[Screenshot]
+
 The xref:key-concepts.adoc#glue[] section is divided into several subsections some of which make sense for all kinds of sources and others only for some.
 Having so many settings available at the same time can be a bit daunting.
 ReaLearn helps you by hiding settings that don't make sense in the current context.

doc/realearn/modules/ROOT/pages/user-interface/mapping-panel/source-section.adoc

@@ -1,6 +1,8 @@
 
 = Source section
 
+image:realearn/screenshots/mapping-panel-source.png[Screenshot]
+
 All xref:source-types.adoc#source-types[] share the following UI elements.
 
 == Learn button

doc/realearn/modules/ROOT/pages/user-interface/mapping-panel/target-section.adoc

@@ -1,6 +1,8 @@
 [[target-section]]
 = Target section
 
+image:realearn/screenshots/mapping-panel-target.png[Screenshot]
+
 All xref:target-types.adoc#target-types[] share the following UI elements.
 
 == Learn button

main/src/infrastructure/test/mod.rs

@@ -1452,6 +1452,7 @@ mod macos_impl {
     use crate::domain::CompartmentKind;
     use crate::infrastructure::plugin::UnitShell;
     use crate::infrastructure::ui::copy_text_to_clipboard;
+    use std::borrow::Cow;
     use std::cell::Ref;
     use std::fs;
     use std::path::PathBuf;
@@ -1480,20 +1481,47 @@ mod macos_impl {
             Screenshooter::new(dirs::download_dir().unwrap().join("realearn-screenshots"));
         // Main panel
         let main_panel_window = Window::from_hwnd(realearn.outcome.fx.floating_window().unwrap());
-        shooter.save(main_panel_window, "main-panel").await;
+        let main_panel_image = shooter.capture(main_panel_window).await;
+        shooter.save_image(&main_panel_image, "main-panel");
+        let main_panel_parts = [
+            ("main-panel-input-output", (14, 110, 714, 124)),
+            ("main-panel-menu-bar", (720, 112, 774, 66)),
+            ("main-panel-let-through-checkboxes", (854, 168, 640, 66)),
+            ("main-panel-show-buttons", (2, 236, 1490, 62)),
+            ("main-panel-preset", (2, 302, 1490, 62)),
+            ("main-panel-group", (6, 362, 994, 62)),
+            ("main-panel-notes-button", (1350, 362, 136, 62)),
+            ("main-panel-mapping-toolbar", (6, 423, 1492, 62)),
+            ("main-panel-mapping-row", (4, 477, 1450, 148)),
+            ("main-panel-bottom", (10, 1224, 1482, 120)),
+        ];
+        for (name, crop) in main_panel_parts {
+            shooter.save_image_part(&main_panel_image, name, crop);
+        }
         // Mapping panel
-        let mapping1 = main_unit_model(main_unit_shell)
+        let mapping = main_unit_model(main_unit_shell)
             .mappings(CompartmentKind::Main)
             .next()
             .cloned()
             .unwrap();
-        let mapping1_panel = main_unit_shell
+        let mapping_panel = main_unit_shell
             .panel()
             .panel_manager()
             .borrow_mut()
-            .edit_mapping(&mapping1);
-        let mapping1_window = mapping1_panel.view_context().require_window();
-        shooter.save(mapping1_window, "mapping-panel").await;
+            .edit_mapping(&mapping);
+        let mapping_window = mapping_panel.view_context().require_window();
+        let mapping_image = shooter.capture(mapping_window).await;
+        shooter.save_image(&mapping_image, "mapping-panel");
+        let mapping_panel_parts = [
+            ("mapping-panel-general", (4, 52, 1434, 190)),
+            ("mapping-panel-source", (0, 240, 558, 462)),
+            ("mapping-panel-target", (564, 240, 878, 462)),
+            ("mapping-panel-glue", (0, 704, 1438, 662)),
+            ("mapping-panel-bottom", (2, 1370, 1438, 172)),
+        ];
+        for (name, crop) in mapping_panel_parts {
+            shooter.save_image_part(&mapping_image, name, crop);
+        }
         // Group panel
         let group_panel = main_unit_shell.panel().header_panel().edit_group().unwrap();
         let group_window = group_panel.view_context().require_window();
@@ -1519,19 +1547,39 @@ mod macos_impl {
         }
 
         pub async fn save(&self, window: Window, name: &str) {
+            let img = self.capture(window).await;
+            self.save_image(&img, name);
+        }
+
+        pub async fn capture(&self, window: Window) -> DynamicImage {
             millis(100).await;
-            let img = xcap::Window::all()
+            xcap::Window::all()
                 .unwrap()
                 .iter()
                 .find(|w| w.app_name() == "REAPER" && w.title() == window.text().unwrap())
                 .expect("couldn't find window to take screenshot from")
-                .capture_image();
-            self.save_img(img.unwrap(), name);
+                .capture_image()
+                .unwrap()
+                .into()
+        }
+
+        pub fn save_image_part(
+            &self,
+            img: &DynamicImage,
+            name: &str,
+            (x, y, width, height): (u32, u32, u32, u32),
+        ) {
+            let cropped_img = img.crop_imm(x, y, width, height);
+            self.save_image(&cropped_img, name);
         }
 
-        fn save_img(&self, img: RgbaImage, name: &str) {
-            let mut img: DynamicImage = img.into();
-            img = img.resize(900, 900, imageops::FilterType::Lanczos3);
+        pub fn save_image(&self, img: &DynamicImage, name: &str) {
+            const MAX_DIM: u32 = 900;
+            let img = if img.height() > MAX_DIM || img.width() > MAX_DIM {
+                Cow::Owned(img.resize(MAX_DIM, MAX_DIM, imageops::FilterType::Lanczos3))
+            } else {
+                Cow::Borrowed(img)
+            };
             img.save(self.dir.join(format!("{name}.png"))).unwrap();
         }
     }