BackupWindow

1. Overview

The BackupWindow module implements the multi-step graphical workflow used to create a snapshot.

Its principal responsibilities are:

  • Coordinates estimation, repository selection, backup execution, and completion pages
  • Provides sidebar and bottom-button navigation
  • Validates each step before advancing
  • Supports standalone and embedded presentation modes

2. Class Structure and Dependencies

public class BackupWindow : 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_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_backup – button used to trigger the corresponding nav backup 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
  • EstimateBox estimate_box – container or reusable widget for estimate
  • BackupDeviceBox backup_dev_box – repository-selection settings page
  • BackupBox backup_box – container or reusable widget for backup
  • BackupFinishBox backup_finish_box – container or reusable widget for backup 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
  • Gtk.Button btn_cancel – button used to trigger the corresponding cancel action
  • Gtk.Button btn_pause – button used to trigger the corresponding pause action
  • Gtk.Button btn_close – button used to trigger the corresponding close action
  • uint tmr_init – numeric state for tmr init
  • int def_width – numeric state for def width
  • int def_height – numeric state for def height
  • bool success – Boolean state for success
  • bool embedded_mode – whether the component is hosted inside another window

The file also contains 3 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

BackupWindow()

public BackupWindow(bool embedded = false)

Initializes the class instance, creates its GTK controls, and prepares the initial state. It connects the close_request signal.

6. Workflow Pages and Enumerations

Tabs

The enumeration defines the following states:

ESTIMATE
BACKUP_DEVICE
BACKUP
BACKUP_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.btrfs_mode
  • App.cron_job_update
  • App.repo
  • App.task

8. Operational Workflow

  1. Open the workflow and initialize the first applicable page
  2. Estimate the initial snapshot size when required
  3. Validate or change the repository location
  4. Run BackupBox and wait for completion
  5. Display BackupFinishBox and persist configuration changes

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.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.repo.

go_prev()

private void go_prev()

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

go_next()

private void go_next()

Validates the current state and advances to the next workflow page.

initialize_tab()

private void initialize_tab()

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

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.

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.

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.
  • 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: