main_window.hpp

1. Overview

The main_window.hpp file implements the primary GTK workflow for source selection, scanning, recovery and reporting.

This is an interface and data-contract file. It declares the public and internal types used by this subsystem, allowing implementation files and callers to share a stable compile-time contract.

Its paired source or interface file is main_window.cpp.

Primary responsibilities:

  • Build dashboard, recovery wizard and about views
  • Enumerate devices and select sources
  • Start background scan and recovery workers
  • Display progress, logs and results
  • Persist language and theme preferences

2. File Identity and Scope

  • Source path: src/main_window.hpp
  • Language: C++
  • File role: interface and data-contract file
  • Physical lines: 189
  • Non-empty lines: 159
  • SHA-256: b40de08b1132f6392b2d15b49d0ddb08ef367bc1f9f8cf60be46966c3620067f

The declarations in this file use the global namespace.

3. Dependencies

3.1 Project Headers

  • device_enumerator.hpp
  • models.hpp
  • recovery_worker.hpp
  • scan_worker.hpp

3.2 Standard and External Headers

  • gtkmm.h
  • giomm.h
  • chrono
  • cstdint
  • string
  • vector

These dependencies define the file’s compile-time integration with the recovery engine, GTK interface, on-disk format decoders, operating-system services, or C++ standard library.

4. Declared Types

  • class MainWindow derives from or specifies public Gtk::Window.
  • enum class ThemeMode.
  • enum class WizardStep.

4.1 Enumeration Values

ThemeMode defines:

  • Dark
  • Light

WizardStep defines:

  • Source
  • Destination
  • Scan
  • Recover

5. Constants and Configuration Values

No preprocessor or compile-time constants were detected as top-level declarations in this file.

6. Data Members and Persistent State

The interface declares the following state-bearing members:

  • ThemeMode current_theme_=ThemeMode::Dark
  • WizardStep current_step_=WizardStep::Source
  • Glib::RefPtr<Gtk::CssProvider> css_provider_
  • Gtk::Box main_box_{Gtk::Orientation::HORIZONTAL,0}
  • Gtk::Stack page_stack_
  • Gtk::Box sidebar_{Gtk::Orientation::VERTICAL,10}
  • Gtk::Box dashboard_page_{Gtk::Orientation::VERTICAL,16}
  • Gtk::Box recovery_page_{Gtk::Orientation::VERTICAL,16}
  • Gtk::Box about_page_{Gtk::Orientation::VERTICAL,24}
  • Gtk::Grid cards_grid_
  • Gtk::Frame card_status_
  • Gtk::Frame card_source_
  • Gtk::Frame card_update_
  • Gtk::Label status_card_label_
  • Gtk::Label source_card_label_
  • Gtk::Label update_card_label_
  • Gtk::Frame devices_frame_
  • Gtk::ScrolledWindow devices_scroller_
  • Gtk::ListBox devices_list_
  • Gtk::Label brand_label_
  • Gtk::Button btn_dashboard_
  • Gtk::Button btn_recovery_
  • Gtk::Button btn_about_
  • Gtk::Button btn_refresh_
  • Gtk::Button btn_theme_dark_
  • Gtk::Button btn_theme_light_
  • Gtk::Button*dashboard_button_=nullptr
  • Gtk::Button*recovery_button_=nullptr
  • Gtk::Button*about_button_=nullptr
  • std::vector<Gtk::Button*> sidebar_buttons_
  • Gtk::DropDown lang_combo_
  • bool lang_changing_=false
  • Gtk::Box recovery_header_{Gtk::Orientation::VERTICAL,8}
  • Gtk::Label recovery_title_
  • Gtk::Label recovery_subtitle_
  • Gtk::Frame wizard_frame_
  • Gtk::Box wizard_root_{Gtk::Orientation::VERTICAL,12}
  • Gtk::Stack wizard_stack_
  • Gtk::Box wizard_nav_{Gtk::Orientation::HORIZONTAL,8}
  • Gtk::Button btn_wizard_back_
  • Gtk::Button btn_wizard_next_
  • Gtk::Label wizard_notice_label_
  • Gtk::Box source_step_box_{Gtk::Orientation::VERTICAL,8}
  • Gtk::Label source_step_label_
  • Gtk::Box source_button_row_{Gtk::Orientation::HORIZONTAL,8}
  • Gtk::Button btn_open_image_
  • Gtk::Button btn_use_selected_device_
  • Gtk::Button btn_launch_elevated_
  • Gtk::ScrolledWindow recovery_devices_scroller_
  • Gtk::ListBox recovery_devices_list_
  • Gtk::Box destination_step_box_{Gtk::Orientation::VERTICAL,8}
  • Gtk::Label destination_step_label_
  • Gtk::Box destination_button_row_{Gtk::Orientation::HORIZONTAL,8}
  • Gtk::Entry entry_output_
  • Gtk::Button btn_choose_destination_
  • Gtk::Box scan_step_box_{Gtk::Orientation::VERTICAL,8}
  • Gtk::Label scan_step_label_
  • Gtk::ProgressBar scan_progress_bar_
  • Gtk::Label scan_status_label_
  • Gtk::Label scan_timer_label_
  • Gtk::Button btn_scan_now_
  • Gtk::Box recover_step_box_{Gtk::Orientation::VERTICAL,8}
  • Gtk::Label recover_step_label_
  • Gtk::Frame results_frame_
  • Gtk::ScrolledWindow results_scroller_
  • Gtk::Box results_tree_box_{Gtk::Orientation::VERTICAL,8}
  • Gtk::Label results_count_label_
  • Gtk::Label results_selected_label_
  • Gtk::Box results_actions_row_{Gtk::Orientation::HORIZONTAL,8}
  • Gtk::Button btn_results_select_all_
  • Gtk::Button btn_results_clear_
  • Gtk::Button btn_recover_now_
  • Gtk::ScrolledWindow log_scroller_
  • Gtk::TextView log_view_
  • Glib::RefPtr<Gtk::TextBuffer> log_buffer_
  • Glib::RefPtr<Gtk::FileDialog> file_dialog_
  • Glib::RefPtr<Gtk::FileDialog> folder_dialog_
  • std::vector<DeviceInfo> devices_
  • std::string selected_source_path_
  • std::string selected_source_label_
  • std::string output_dir_
  • ScanReport last_report_
  • std::vector<bool> result_selection_
  • std::vector<Gtk::CheckButton*> result_check_buttons_
  • ScanWorker scan_worker_
  • RecoveryWorker recovery_worker_
  • ScanProgress last_scan_progress_
  • sigc::connection scan_timer_connection_
  • std::chrono::steady_clock::time_point scan_started_at_{}

These members hold configuration, parser context, UI widgets, source references, progress state, recovered metadata, or temporary resources according to the owning type.

7. API and Function Inventory

The following callable interfaces or definitions were detected:

  • ~MainWindow()override – Destroys the object and releases resources owned by the instance.
  • void build_headerbar() – Constructs the requested object, data structure or user-interface component.
  • void build_sidebar() – Constructs the requested object, data structure or user-interface component.
  • void build_dashboard() – Constructs the requested object, data structure or user-interface component.
  • void build_recovery_page() – Constructs the requested object, data structure or user-interface component.
  • void build_wizard() – Constructs the requested object, data structure or user-interface component.
  • void build_about_page() – Constructs the requested object, data structure or user-interface component.
  • void update_action_controls() – Refreshes the related state or presentation from current data.
  • void apply_theme(ThemeMode mode) – Implements the operation identified by this API and updates or returns the associated state.
  • void apply_inline_css() – Implements the operation identified by this API and updates or returns the associated state.
  • void update_theme_buttons() – Refreshes the related state or presentation from current data.
  • void activate_sidebar_button(Gtk::Button*button) – Implements the operation identified by this API and updates or returns the associated state.
  • void refresh_devices() – Refreshes the related state or presentation from current data.
  • void populate_device_lists() – Refreshes the related state or presentation from current data.
  • void select_source(const std::string&path,const std::string&label) – Implements the operation identified by this API and updates or returns the associated state.
  • void update_source_state() – Refreshes the related state or presentation from current data.
  • void update_wizard_step() – Refreshes the related state or presentation from current data.
  • void append_log(const std::string&line) – Updates the relevant collection or range state.
  • void on_sidebar_dashboard() – Handles the related event, callback or user action.
  • void on_sidebar_recovery() – Handles the related event, callback or user action.
  • void on_sidebar_about() – Handles the related event, callback or user action.
  • void on_refresh_devices() – Handles the related event, callback or user action.
  • void on_language_changed() – Handles the related event, callback or user action.
  • void on_open_image() – Handles the related event, callback or user action.
  • void on_choose_destination() – Handles the related event, callback or user action.
  • void on_use_selected_device() – Handles the related event, callback or user action.
  • void on_dashboard_device_activated(Gtk::ListBoxRow*row) – Handles the related event, callback or user action.
  • void on_recovery_device_activated(Gtk::ListBoxRow*row) – Handles the related event, callback or user action.
  • void on_theme_dark() – Handles the related event, callback or user action.
  • void on_theme_light() – Handles the related event, callback or user action.
  • void on_wizard_back() – Handles the related event, callback or user action.
  • void on_wizard_next() – Handles the related event, callback or user action.
  • void on_scan_now() – Handles the related event, callback or user action.
  • void on_recover_now() – Handles the related event, callback or user action.
  • void on_launch_elevated() – Handles the related event, callback or user action.
  • void on_scan_progress(const ScanProgress&progress) – Handles the related event, callback or user action.
  • void on_scan_completed(const ScanReport&report) – Handles the related event, callback or user action.
  • void on_recovery_completed(const RecoveryResult&result) – Handles the related event, callback or user action.
  • void populate_scan_results(const ScanReport&report) – Refreshes the related state or presentation from current data.
  • void update_selected_results_state() – Refreshes the related state or presentation from current data.
  • std::vector<size_t> selected_result_indices()const – Implements the operation identified by this API and updates or returns the associated state.
  • void set_all_results_selected(bool selected) – Persists or exports the supplied state to the relevant destination.
  • static std::string result_group_label(const ScanResult&result) – Implements the operation identified by this API and updates or returns the associated state.
  • static std::string result_subgroup_label(const ScanResult&result) – Implements the operation identified by this API and updates or returns the associated state.
  • void minimize_window() – Implements the operation identified by this API and updates or returns the associated state.
  • void hide_window() – Implements the operation identified by this API and updates or returns the associated state.
  • static std::string human_size(uint64_t bytes) – Implements the operation identified by this API and updates or returns the associated state.
  • static std::string read_language() – Reads or derives the requested information and returns or stores the decoded result.
  • static void save_language(const std::string&lang_code) – Persists or exports the supplied state to the relevant destination.
  • static std::string read_theme() – Reads or derives the requested information and returns or stores the decoded result.
  • static void save_theme(const std::string&theme_code) – Persists or exports the supplied state to the relevant destination.

8. Operational Flow

The subsystem represented by this file normally participates in the following flow:

  1. Build dashboard, recovery wizard and about views.
  2. Enumerate devices and select sources.
  3. Start background scan and recovery workers.
  4. Display progress, logs and results.
  5. Persist language and theme preferences.
  6. Expose or execute the detected APIs: ~MainWindow, build_headerbar, build_sidebar, build_dashboard, build_recovery_page, build_wizard, build_about_page, update_action_controls, apply_theme, apply_inline_css, update_theme_buttons, activate_sidebar_button, refresh_devices, populate_device_lists, select_source, update_source_state, update_wizard_step, append_log and additional helpers.
  7. Return explicit results, progress data, recovered records, or diagnostics to the calling layer.

9. Validation and Error Handling

  • Byte offsets, sizes and lengths must be validated before arithmetic and before every read to avoid overflow and out-of-bounds access.
  • Input and output paths require existence checks, permission handling and safe destination construction.

10. Runtime, Concurrency, and Resource Management

  • GTK lifecycle: widget ownership, signal connections and main-thread affinity must be preserved.
  • GTK objects and callbacks must obey main-thread affinity and signal lifetime rules.

11. Security and Data-Recovery Considerations

  • Recovery code should prefer read-only source access and avoid writing to the original damaged medium.
  • Raw devices and image files are treated as untrusted binary input; every offset and length must remain bounded by the source size.
  • Recovered names and destination paths must be sanitized to prevent directory traversal and accidental overwrite outside the selected export directory.

12. Implementation Considerations

  • Changes to public declarations can affect every translation unit that includes this header and should preserve binary and source compatibility where required.
  • State-bearing members should have explicit ownership and initialization semantics, especially for references, pointers, file descriptors and GTK widgets.
  • Large-device arithmetic uses 64-bit values; additions and multiplications should be checked before use as offsets or allocation sizes.

13. Integration with the Recovery Pipeline

  • The file belongs to the application startup or presentation layer.
  • It receives or presents data produced by scan and recovery services.
  • Long-running operations should remain delegated to worker classes rather than blocking the GTK main loop.

14. Licensing and Provenance

No explicit copyright or software-license statement was detected in the opening section of this individual file. Distribution terms should therefore be verified against the project-level license and repository metadata.

The SHA-256 value in this document can be used to associate the generated documentation with the exact source version analyzed.

Published on:
Last updated on: