RestoreWindow

1. Overview

The RestoreWindow module implements the complete multi-step snapshot restore workflow.

Its principal responsibilities are:

  • Coordinates target devices, exclusions, application data, checks, logs, users, summary, execution, and finish pages
  • Validates each page before navigation
  • Supports dry-run and actual restoration
  • Supports embedded and standalone presentation modes

2. Class Structure and Dependencies

public class RestoreWindow : Gtk.Window

The source imports:

  • Gtk
  • Gee
  • TeeJee.Logging
  • TeeJee.FileSystem
  • TeeJee.JsonHelper
  • TeeJee.ProcessHelper
  • TeeJee.GtkHelper
  • TeeJee.System
  • TeeJee.Misc

The GTK inheritance and imported modules allow the component to participate in the application event loop, share the central backup state, and construct native GTK4 controls.

3. Primary Runtime State

The principal fields declared by the module include:

  • Gtk.Box root_box – top-level container of the window or embedded page
  • Gtk.Box sidebar – navigation sidebar container
  • Gtk.Box content_box – container holding the active page and navigation controls
  • Gtk.Box header_box – container or reusable widget for header
  • Gtk.Box body_box – container or reusable widget for body
  • Gtk.Box bbox_action – Box widget used by the interface
  • Gtk.Stack page_stack – GTK stack containing workflow pages
  • int current_page – index of the currently active workflow page
  • Gtk.Button btn_nav_target – button used to trigger the corresponding nav target action
  • Gtk.Button btn_nav_check – button used to trigger the corresponding nav check action
  • Gtk.Button btn_nav_log – button used to trigger the corresponding nav log action
  • Gtk.Button btn_nav_users – button used to trigger the corresponding nav users action
  • Gtk.Button btn_nav_summary – button used to trigger the corresponding nav summary action
  • Gtk.Button btn_nav_restore – button used to trigger the corresponding nav restore action
  • Gtk.Button btn_nav_finish – button used to trigger the corresponding nav finish action
  • Gtk.Button? current_nav_btn – Button? widget used by the interface
  • Gtk.Label lbl_page_title – label used to display page title information
  • RestoreDeviceBox restore_device_box – container or reusable widget for restore device
  • RestoreExcludeBox restore_exclude_box – container or reusable widget for restore exclude
  • ExcludeAppsBox exclude_apps_box – container or reusable widget for exclude apps
  • RestoreSummaryBox summary_box – container or reusable widget for summary
  • RestoreBox check_box – container or reusable widget for check
  • RsyncLogBox log_box – container or reusable widget for log
  • RestoreBox restore_box – container or reusable widget for restore
  • UsersBox users_box – per-user inclusion settings page
  • RestoreFinishBox restore_finish_box – container or reusable widget for restore finish
  • Gtk.Button btn_prev – button used to trigger the corresponding prev action
  • Gtk.Button btn_next – button used to trigger the corresponding next action

The file also contains 11 additional supporting fields used for layout, navigation, or internal state.

4. User Interface Composition

The module directly constructs the following GTK widget types:

  • Gtk.Box – layout containers
  • Gtk.Button – action and navigation buttons
  • Gtk.Image – themed icons and state illustrations
  • Gtk.Label – headings, descriptions, and status text
  • Gtk.Stack – multi-page content navigation

Event-driven behavior is connected through signals such as:

clicked
close_request

5. Initialization

RestoreWindow()

public RestoreWindow(bool embedded = false)

Initializes the class instance, creates its GTK controls, and prepares the initial state. It reads or updates central state through App.mirror_system. It connects the close_request signal.

6. Workflow Pages and Enumerations

Tabs

The enumeration defines the following states:

TARGET_DEVICE
RESTORE_EXCLUDE
EXCLUDE_APPS
CHECK
SHOW_LOG
USERS
SUMMARY
RESTORE
FINISH

These values provide stable identifiers for navigation, validation, and page-specific initialization.

7. Central Controller Integration

The module reads or modifies the following Main controller members through the global App object:

  • App.add_app_exclude_entries
  • App.btrfs_mode
  • App.cron_job_update
  • App.dry_run
  • App.mirror_system
  • App.save_exclude_list_selections
  • App.snapshot_to_restore
  • App.task

8. Operational Workflow

  1. Initialize restore state from the selected snapshot
  2. Map target devices and boot options
  3. Apply restore exclusions and application selections
  4. Review checks, logs, users, and final summary
  5. Run RestoreBox and display RestoreFinishBox

9. Method Reference

build_ui()

private void build_ui()

Constructs the complete GTK widget hierarchy for the component. It creates Gtk.Box where required.

build_sidebar()

private void build_sidebar()

Creates the workflow or application navigation sidebar. It creates Gtk.Box, Gtk.Image, Gtk.Label where required.

make_nav_button()

private Gtk.Button make_nav_button(string icon_name, string label_text)

Factory helper that creates nav button. It creates Gtk.Box, Gtk.Button, Gtk.Label where required.

build_content()

private void build_content()

Creates the main content region and page container. It creates Gtk.Box, Gtk.Label, Gtk.Stack where required.

wrap_page()

private Gtk.Widget wrap_page(Gtk.Widget child)

Implements the wrap page operation. It creates Gtk.Box where required.

build_pages()

private void build_pages()

Instantiates and registers all pages used by the workflow. It creates Gtk.Label where required.

init_delayed()

private bool init_delayed()

Performs initialization scheduled after the window has been presented.

on_close_request()

private bool on_close_request()

Handles a request to close the window and coordinates cleanup or state persistence.

save_changes()

private void save_changes()

Copies UI selections into the central configuration and persists the result. It reads or updates central state through App.cron_job_update.

create_actions()

private void create_actions()

Creates action buttons and connects their callbacks. It reads or updates central state through App.dry_run, App.task. It creates Gtk.Box where required. It connects the clicked signal.

action_buttons_set_initial_visibility()

private void action_buttons_set_initial_visibility(bool visible)

Implements the action buttons set initial visibility operation.

go_first()

private void go_first()

Moves the workflow to its first page. It reads or updates central state through App.btrfs_mode, App.snapshot_to_restore.

go_prev()

private void go_prev()

Moves to the previous valid workflow page. It reads or updates central state through App.btrfs_mode, App.snapshot_to_restore.

go_next()

private void go_next()

Validates the current state and advances to the next workflow page. It reads or updates central state through App.btrfs_mode.

initialize_tab()

private void initialize_tab()

Refreshes and initializes the page that has just become active. It reads or updates central state through App.dry_run, App.snapshot_to_restore.

validate_current_tab()

private bool validate_current_tab()

Validates the active workflow page before navigation continues. It reads or updates central state through App.add_app_exclude_entries, App.save_exclude_list_selections.

clear_sidebar_selection()

private void clear_sidebar_selection()

Implements the clear sidebar selection operation.

set_sidebar_active()

private void set_sidebar_active(Gtk.Button btn)

Sets sidebar active and updates dependent UI state.

update_sidebar_state()

private void update_sidebar_state()

Updates sidebar state to reflect the current state.

update_page_title()

private void update_page_title()

Updates page title to reflect the current state. It reads or updates central state through App.mirror_system.

set_page()

private void set_page(int page)

Activates a specific workflow page and updates navigation state.

detach_root_widget()

public Gtk.Widget detach_root_widget()

Detaches and returns the component root widget for embedding in another window.

themed_icon()

private Gtk.Image themed_icon(string icon_name, int size)

Creates a themed GTK image at the requested size.

reload_themed_icons()

public void reload_themed_icons()

Reloads icons after a theme change.

10. External Resources and Paths

The component does not directly define protected filesystem paths or external command strings.

11. Data and Event Flow

  1. Construct the component and initialize its child controls
  2. React to GTK signals generated by navigation, selections, and action controls
  3. Read or update central backup and restore state through the global controller
  4. Persist the final selections when the workflow is accepted or closed

12. Runtime and Security Considerations

  • Shared controller state: the component reads and modifies the global App controller used by the surrounding workflow.
  • Device safety: device selections are validated before backup or restore operations continue.
  • Signal-driven behavior: GTK callbacks update the model and interface when controls are activated or changed.
  • Reusable presentation: the component can be hosted as a standalone window or embedded inside the main navigation stack.
  • Dry-run support: the interface can invoke validation or simulation paths without committing the final restore operation.
  • Schedule persistence: changes can require regeneration of the application Cron configuration.

13. Implementation Considerations

  • Global coupling: the class depends on the process-wide App object rather than receiving a controller through dependency injection.
  • Embedding contract: parent containers must use detach_root_widget() only after the window has initialized its root widget.

14. Licensing

The source header contains the following copyright notices:

Copyright 2012-2018 Tony George <teejeetech@gmail.com>

The file is distributed under the GNU General Public License version 2 or later.

Published on:
Last updated on: