SettingsWindow

1. Overview

The SettingsWindow module implements the main settings workflow.

Its principal responsibilities are:

  • Hosts snapshot backend, repository, schedule, exclusions, and user settings
  • Provides sidebar and bottom navigation
  • Saves changes and refreshes Cron state
  • Supports embedding in MainWindow

2. Class Structure and Dependencies

public class SettingsWindow : 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 content_header_box – container or reusable widget for content header
  • Gtk.Box content_body_box – container or reusable widget for content body
  • Gtk.Box bottom_bar – Box widget used by the interface
  • Gtk.Stack stack – GTK stack containing selectable pages
  • SnapshotBackendBox backend_box – snapshot-backend settings page
  • BackupDeviceBox backup_dev_box – repository-selection settings page
  • ScheduleBox schedule_box – schedule and retention settings page
  • ExcludeBox exclude_box – custom exclusion settings page
  • UsersBox users_box – per-user inclusion settings page
  • MiscBox misc_box – container or reusable widget for misc
  • Gtk.Button btn_type – button used to trigger the corresponding type action
  • Gtk.Button btn_location – button used to trigger the corresponding location action
  • Gtk.Button btn_schedule – button used to trigger the corresponding schedule action
  • Gtk.Button btn_users – button used to trigger the corresponding users action
  • Gtk.Button btn_filters – button used to trigger the corresponding filters action
  • Gtk.Button btn_misc – button used to trigger the corresponding misc action
  • Gtk.Button btn_close – button used to trigger the corresponding close action
  • 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.Label lbl_page_title – label used to display page title information
  • Gee.ArrayList<Gtk.Button> nav_buttons – collection of nav buttons items
  • 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 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
type_changed

5. Initialization

SettingsWindow()

public SettingsWindow(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:

BACKUP_TYPE
BACKUP_DEVICE
SCHEDULE
EXCLUDE

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

8. Operational Workflow

  1. Load the current backend and repository state
  2. Allow navigation between settings pages
  3. Apply exclusion and user changes
  4. Save central configuration and update Cron jobs

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.

build_content()

private void build_content()

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

build_pages()

private void build_pages()

Instantiates and registers all pages used by the workflow.

connect_signals()

private void connect_signals()

Connects widget signals to the corresponding event handlers. It reads or updates central state through App.btrfs_mode. It connects the clicked, type_changed signals.

create_nav_button()

private Gtk.Button create_nav_button(string icon_name, string text)

Creates nav button required by the workflow. It creates Gtk.Box, Gtk.Button, Gtk.Label where required.

get_tab_order()

private Gee.ArrayList<string> get_tab_order()

Returns tab order derived from the current model. It reads or updates central state through App.btrfs_mode.

get_current_tab_index()

private int get_current_tab_index()

Returns current tab index derived from the current model.

activate_tab_by_name()

private void activate_tab_by_name(string name)

Implements the activate tab by name operation.

activate_relative_tab()

private void activate_relative_tab(int delta)

Implements the activate relative tab operation.

update_bottom_navigation()

private void update_bottom_navigation()

Updates bottom navigation to reflect the current state.

activate_tab()

private void activate_tab(string name, Gtk.Button active_button, string title_text)

Implements the activate tab operation.

clear_nav_selection()

private void clear_nav_selection()

Implements the clear nav selection 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.

detach_root_widget()

public Gtk.Widget detach_root_widget()

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

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.

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 &lt;teejeetech@gmail.com&gt;

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

Published on:
Last updated on: