MainWindow.hpp

1. Overview

The MainWindow.hpp header defines the MainWindow class, the primary GTKmm (GTK4) top-level window for the BastionGuard desktop application. This component orchestrates the full UI shell: it composes the main layout (sidebar + content stack), instantiates and hosts all application pages, and manages window-level behaviors such as intercepting the close request to minimize to the system tray (implementation-defined).

Functionally, MainWindow provides:

  • Application shell composition (header bar, sidebar navigation, stacked pages)
  • Page lifecycle ownership and navigation entry points (e.g., show dashboard)
  • Integration with configuration/state objects (e.g., ClamdConfig)
  • Lazy/optional page allocation via pointers for heavier or conditional modules
  • Settings window management as a separate top-level window
  • Close interception to hide/minimize to tray instead of exiting

2. Dependencies and Includes

#include <gtkmm.h>
#include "DashboardPage.hpp"
#include "ScanPage.hpp"
#include "LogPage.hpp"
#include "SettingsPage.hpp"
#include "QuarantinePage.hpp"
#include "UpdatePage.hpp"
#include "AboutPage.hpp"
#include "DonatePage.hpp"
#include "BankPage.hpp"
#include "PrivacyPage.hpp"
#include "AntiRansomwarePage.hpp"
#include "SettingsWindow.hpp"
#include "usb/USBScanPage.hpp"
#include "IdentityLeakPage/ui/IdentityLeakPage.hpp"
#include "SambaPage.hpp"
  • gtkmm.h – GTK4 C++ windowing and widgets
  • Page headers – the set of application pages hosted in the main stack (dashboard, scan, logs, updates, etc.)
  • SettingsWindow – separate configuration window
  • USB / Identity Leak / Samba modules – optional or specialized feature pages

3. Class Declaration and Scope

class MainWindow : public Gtk::Window

The class derives from Gtk::Window, making it the primary top-level container responsible for application-level navigation, window lifecycle, and shell behaviors.

The header forward-declares ClamdConfig to avoid including the full implementation and reduce coupling:

// FWD to avoid including the implementation here
class ClamdConfig;

4. Public Interface

4.1 Constructor / Destructor

MainWindow();
~MainWindow() override = default;

The constructor is responsible for building the full UI shell (headerbar, sidebar, stack, and page wiring). The destructor is defaulted; any owned resources that require explicit teardown must be handled elsewhere (for example, by disconnecting signals, destroying auxiliary windows, and managing pointer-owned pages).

4.2 Navigation Entry Points

void showDashboard();
void open_settings_window();
  • showDashboard() – programmatically navigates to the dashboard page (e.g., at startup or after certain actions)
  • open_settings_window() – opens (or focuses) the settings window as a separate top-level UI

5. UI Components

MainWindow defines a two-pane application shell: a left navigation sidebar and a right content area implemented as a GTK stack. The headerbar is built separately to provide window-level actions and app identity.

5.1 Main Layout (Sidebar + Stack)

Gtk::Box  mainBox{Gtk::Orientation::HORIZONTAL}; // padding managed via CSS
Gtk::Stack stack_;
std::vector<Gtk::Button*> sidebar_buttons_;
  • mainBox – horizontal root container holding sidebar (left) and content stack (right)
  • stack_ – page switcher container; only one child is visible at a time
  • sidebar_buttons_ – collection of sidebar navigation buttons to coordinate activation state

5.2 Hosted Pages

The window owns and coordinates a set of feature pages. Some are instantiated as values (always present), while others are pointer-based (optional/lazy or conditionally available).

AboutPage      about_page_;
DonatePage     donate_page_;
DashboardPage  dashboard_page_;
ScanPage       scan_page_{*this};
LogPage        log_page_;
QuarantinePage quarantine_page_;
UpdatePage     update_page_;
ClamdConfig clamdConfig_;
SettingsWindow* settings_window_ = nullptr;
BankPage*             bank_page_ = nullptr;
PrivacyPage*          privacy_page_;
AntiRansomwarePage*   anti_ransomware_page_ = nullptr;
USBScanPage*          usb_page_ = nullptr;
SambaPage*            samba_page_ = nullptr;
IdentityLeakPage*     identity_leak_page_ = nullptr;
  • Value-owned pages – constructed as part of MainWindow lifetime and typically always available
  • Pointer-owned pages – may be allocated lazily, depend on runtime capabilities, or be optional modules
  • scan_page_{*this} – indicates the scan page depends on the main window instance (e.g., to call back into window actions)
  • settings_window_ – separate settings UI; pointer suggests on-demand creation and reuse
  • clamdConfig_ – configuration/state object used when building UI and features (e.g., sidebar construction)

5.3 Sidebar Activation State

Gtk::Button* dashboard_button_ = nullptr;
void activate_sidebar_button(Gtk::Button* btn);

A dedicated pointer for the dashboard button is maintained (likely to enforce a default selection), and a helper method manages the active/selected state of sidebar buttons (styling, toggling, and/or stack switching).

6. Internal State and Data Model

MainWindow primarily models UI composition and page ownership. Key internal state includes:

  • Layout containers (mainBox, stack_) defining the shell structure
  • Navigation controls (sidebar_buttons_, dashboard_button_)
  • Page instances (value-owned and pointer-owned modules)
  • Auxiliary window pointer (settings_window_)
  • Configuration/state object (clamdConfig_) used during UI initialization

7. User Actions (Callbacks)

Window-level event handling is implemented by overriding GTK close semantics. Other user actions (sidebar navigation, settings opening, etc.) are wired in the implementation through helper builders.

7.1 Close Request Interception

bool on_close_request() override;

Intercepts the window close request (the “X” action). The header documents the intent: hide/minimize to the system tray rather than exiting. The method returns a boolean to indicate whether the event has been handled (exact semantics depend on GTK4 conventions in the implementation).

8. Internal Logic

8.1 UI Builders

void build_headerbar();
void build_sidebar(ClamdConfig& clamdConfig);
  • build_headerbar() – constructs the window header bar (app title, actions, window controls as configured)
  • build_sidebar() – builds the left navigation and wires buttons to stack pages; accepts configuration/state

8.2 Sidebar Button Activation

void activate_sidebar_button(Gtk::Button* btn);

Centralizes sidebar activation logic to ensure consistent UI behavior. Typical responsibilities include:

  • Applying/removing CSS classes to reflect the active page
  • Keeping the stack selection and sidebar highlight in sync
  • Preventing inconsistent states when programmatic navigation occurs

8.3 Window Utility

void minimize();

Utility method used to minimize or hide the window, commonly in support of tray behavior when the user closes the window or when the application transitions to background operation (implementation-defined).

9. Auto-Update (Scheduled Refresh)

This header does not define a central auto-update timer for the main window. Periodic operations, if any, are expected to be implemented at the page level (e.g., log refresh pages) or within service components owned by the application.

10. Settings Storage

The main window does not declare direct settings persistence APIs. Configuration concerns are likely handled via:

  • The dedicated SettingsWindow and corresponding settings components
  • The configuration/state object clamdConfig_
  • Page-level settings (e.g., individual pages persisting preferences)

11. Helper Functions and Filesystem Layout

No filesystem path helpers are declared in this header. Filesystem and system integration are delegated to feature pages and configuration modules (e.g., quarantine, updates, bank list, identity leak scanning).

12. Runtime and Security Considerations

  • Lifetime management: pointer-owned pages and auxiliary windows (settings_window_, module pages) must be created and destroyed deterministically to avoid leaks and dangling signal connections.
  • Close-to-tray behavior: intercepting close requests should be transparent to users; provide clear UI affordances to exit the application explicitly if needed.
  • Main loop responsiveness: avoid performing heavy initialization for all pages at startup. Pointer/lazy pages can reduce startup latency and memory usage.
  • Privilege boundaries: pages performing privileged operations (updates, quarantine, system integration) should enforce authorization checks and provide clear failure reporting.
  • Consistent navigation state: ensure sidebar button activation and stack page switching cannot diverge, especially when navigation occurs programmatically (e.g., showDashboard()).
Published on:
Last updated on: