SetupWizardWindow

1. Overview

The SetupWizardWindow module implements the first-run guided configuration workflow.

Its principal responsibilities are:

  • Detects importable Timeshift state
  • Selects the snapshot backend
  • Estimates initial snapshot size
  • Selects the repository
  • Configures schedules and users
  • Completes first-run initialization

2. Class Structure and Dependencies

public class SetupWizardWindow : Gtk.Window

The source imports:

  • Gtk
  • Gee
  • Json
  • 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 actions_box – container or reusable widget for actions
  • Gtk.Stack stack – GTK stack containing selectable pages
  • Gtk.Button btn_nav_import – button used to trigger the corresponding nav import action
  • Gtk.Button btn_nav_backend – button used to trigger the corresponding nav backend action
  • Gtk.Button btn_nav_estimate – button used to trigger the corresponding nav estimate action
  • Gtk.Button btn_nav_location – button used to trigger the corresponding nav location action
  • Gtk.Button btn_nav_schedule – button used to trigger the corresponding nav schedule action
  • Gtk.Button btn_nav_users – button used to trigger the corresponding nav users 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
  • Gtk.Box timeshift_page_box – container or reusable widget for timeshift page
  • Gtk.Label lbl_timeshift_title – label used to display timeshift title information
  • Gtk.Label lbl_timeshift_desc – label used to display timeshift desc information
  • Gtk.Label lbl_timeshift_found – label used to display timeshift found information
  • Gtk.CheckButton radio_import_yes – CheckButton widget used by the interface
  • Gtk.CheckButton radio_import_no – CheckButton widget used by the interface
  • Gtk.Label lbl_timeshift_path – label used to display timeshift path information
  • Gtk.Label lbl_timeshift_note – label used to display timeshift note information
  • bool timeshift_available – Boolean state for timeshift available
  • bool timeshift_import_done – Boolean state for timeshift import done
  • int timeshift_backup_count – numeric state for timeshift backup count
  • string timeshift_config_path – text value for timeshift config path

The file also contains 20 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.CheckButton – Boolean or mutually exclusive choices
  • Gtk.Image – themed icons and state illustrations
  • Gtk.Label – headings, descriptions, and status text
  • Gtk.Separator – visual section separators
  • Gtk.Stack – multi-page content navigation

Event-driven behavior is connected through signals such as:

clicked
close_request

5. Initialization

SetupWizardWindow()

public SetupWizardWindow(bool embedded = false)

Initializes the class instance, creates its GTK controls, and prepares the initial state. It reads or updates central state through App.first_run, App.schedule_boot, App.schedule_daily, App.schedule_hourly, App.schedule_monthly, App.schedule_weekly. It connects the close_request signal.

6. Workflow Pages and Enumerations

Tabs

The enumeration defines the following states:

IMPORT_TIMESHIFT
SNAPSHOT_BACKEND
ESTIMATE
BACKUP_DEVICE
SCHEDULE
USERS
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.backup_uuid
  • App.btrfs_mode
  • App.cron_job_update
  • App.first_run
  • App.import_timeshift_config_if_available
  • App.initialize_repo
  • App.live_system
  • App.repo
  • App.schedule_boot
  • App.schedule_daily
  • App.schedule_hourly
  • App.schedule_monthly
  • App.schedule_weekly
  • App.task

8. Operational Workflow

  1. Probe compatible Timeshift configurations and mounted repositories
  2. Optionally import existing configuration
  3. Choose RSYNC or BTRFS
  4. Estimate storage requirements and select a repository
  5. Configure schedules and user-data rules
  6. Clear first-run state and save the completed configuration

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.

build_pages()

private void build_pages()

Instantiates and registers all pages used by the workflow.

build_timeshift_page()

private void build_timeshift_page()

Builds the timeshift page portion of the interface. It creates Gtk.Box, Gtk.CheckButton, Gtk.Label, Gtk.Separator where required.

wrap_page()

private Gtk.Widget wrap_page(Gtk.Widget child)

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

detect_timeshift_state()

private void detect_timeshift_state()

Implements the detect timeshift state operation.

probe_timeshift_snapshots_from_mounts()

private int probe_timeshift_snapshots_from_mounts()

Implements the probe timeshift snapshots from mounts operation. It reads or updates central state through App.backup_uuid.

probe_timeshift_snapshot_count()

private int probe_timeshift_snapshot_count(string config_path)

Implements the probe timeshift snapshot count operation.

refresh_timeshift_page()

private void refresh_timeshift_page()

Refreshes timeshift page from the current application state. It reads or updates central state through App.backup_uuid.

should_import_timeshift()

private bool should_import_timeshift()

Implements the should import timeshift operation.

run_timeshift_import()

private bool run_timeshift_import()

Implements the run timeshift import operation. It reads or updates central state through App.import_timeshift_config_if_available, App.initialize_repo, App.repo.

create_actions()

private void create_actions()

Creates action buttons and connects their callbacks. It reads or updates central state through App.task. It creates Gtk.Box, Gtk.Button 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.

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. It reads or updates central state through App.first_run, App.schedule_boot, App.schedule_daily, App.schedule_hourly, App.schedule_monthly, App.schedule_weekly.

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, App.first_run.

detach_root_widget()

public Gtk.Widget detach_root_widget()

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

go_first()

private void go_first()

Moves the workflow to its first page.

go_prev()

private void go_prev()

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

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, App.live_system.

initialize_tab()

private void initialize_tab()

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

validate_current_tab()

private bool validate_current_tab()

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

set_page()

private void set_page(Tabs tab)

Activates a specific workflow page and updates navigation state.

get_current_tab()

private Tabs get_current_tab()

Returns current tab derived from the current model.

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.

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.

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 source references the following relevant paths, command fragments, or resource identifiers:

/etc/timeshift/timeshift.json
/etc/timeshift.json

11. Data and Event Flow

  1. Construct the component and initialize its child controls
  2. Load the current model state into the interface
  3. React to GTK signals generated by navigation, selections, and action controls
  4. Read or update central backup and restore state through the global controller
  5. 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.
  • 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: