SettingsWindow.hpp

1. Overview

The SettingsWindow.hpp header defines the SettingsWindow class, a GTKmm (GTK4) top-level window used as BastionGuard’s Settings container. It provides the main structural elements for a modern settings experience: a custom header bar, a sidebar navigation, and a stack-based content area that hosts the SettingsPage UI.

The class focuses on layout and navigation orchestration, while delegating the actual settings content and page logic to SettingsPage.

  • Gtk::Window – top-level window, modal-style container behavior (implementation-defined)
  • Gtk::Box – horizontal split layout (sidebar + content)
  • Gtk::Stack – content host for the settings root widget
  • SettingsPage – provides the actual page set and the page switching API
  • ClamdConfig – configuration model injected into the settings page tree

2. Header Dependencies

#pragma once
#include <gtkmm.h>
#include "SettingsPage.hpp"
#include "ClamdConfig.hpp"
#include <vector>
#include <string>
  • <gtkmm.h> – GTK4 C++ widgets, layout primitives, and signals
  • SettingsPage.hpp – settings content container and navigation entry point
  • ClamdConfig.hpp – ClamAV configuration model passed into the settings UI
  • <vector> – stores pointers to leaf buttons for active-state management
  • <string> – label/icon path parameters for sidebar button factories

3. Class Declaration and Role

class SettingsWindow : public Gtk::Window

SettingsWindow derives from Gtk::Window, making it the primary top-level container for the Settings UI. It owns layout widgets (main box, stack, sidebar) and controls page routing by calling methods on SettingsPage.

4. Public Interface

4.1 Constructor

explicit SettingsWindow(ClamdConfig& config);

Constructs the settings window and injects the ClamdConfig model reference into the internal SettingsPage hierarchy. This design ensures that the full settings UI tree shares a consistent, mutable configuration model.

5. Internal Layout Widgets

Gtk::Box    mainBox_ {Gtk::Orientation::HORIZONTAL, 0};
Gtk::Stack  stack_;
  • mainBox_ – the top-level horizontal container splitting sidebar and content
  • stack_ – the content container used to host the settings root widget (typically a single SettingsPage instance) and enable view switching patterns if expanded in the future

6. Owned/Tracked Child Components

SettingsPage*             settingsPage_    = nullptr;
Gtk::Box*                 sidebar_box_     = nullptr;
std::vector<Gtk::Button*> all_leaf_buttons_;
  • settingsPage_ – pointer to the instantiated settings content widget; used for page routing (e.g., goto_page()) and configuration injection
  • sidebar_box_ – pointer to the sidebar container widget
  • all_leaf_buttons_ – registry of leaf buttons used to maintain “active selection” styling (only one leaf can be active at a time)

7. Private Methods (Layout Construction)

7.1 Header Bar Builder

void build_headerbar();

Creates and configures the custom header bar, including window controls (typically a custom close button) and any brand accent elements. Implementation details (CSS classes, icon loading, button wiring) are handled in the corresponding .cpp file.

7.2 Sidebar Builder

void build_sidebar(ClamdConfig& config);

Constructs the sidebar navigation UI, including:

  • Leaf entries that navigate directly to a page index
  • Expandable groups with nested sub-pages (submenu boxes)
  • Default selection initialization (activating the first leaf)

The ClamdConfig reference is accepted to enable future sidebar logic driven by configuration state (even if the current implementation does not require it for layout alone).

8. Sidebar Button Factory Methods

8.1 Group Button Factory (Expandable)

Gtk::Button* make_group_button(const std::string& icon_path,
                               const std::string& label_text,
                               Gtk::Box** out_submenu = nullptr);

Creates a sidebar group entry (typically “section headers” like Anti-Ransomware/Services) with:

  • Optional icon (from icon_path)
  • Label (label_text)
  • Chevron indicator and click handler
  • Optional submenu box returned via out_submenu. When present, this submenu can be toggled visible/hidden to implement collapsible sections.

8.2 Leaf Button Factory (Navigable Item)

Gtk::Button* make_leaf_button(const std::string& label_text,
                              bool indent = false);

Creates a clickable leaf item representing a concrete settings destination. Leaf buttons are tracked in all_leaf_buttons_ to support exclusive “active” styling. When indent is true, an additional CSS class may be applied to render the leaf as a nested child of a group.

9. Active Selection and Visual State

void activate_button(Gtk::Button* btn);

Ensures only one leaf button is marked active at any time by removing the “active” CSS class from all tracked leaf buttons and applying it to the selected one. This improves UX clarity by showing the current navigation target.

10. Runtime and Maintenance Considerations

  • Ownership semantics: pointers like settingsPage_ and sidebar_box_ are typically managed by GTK (via Gtk::make_managed) and kept here only for direct access and navigation.
  • Styling strategy: the design assumes CSS-driven theming. Leaf/button activation depends on stable style class names and consistent theme assets.
  • Extensibility: adding new pages typically involves adding sidebar entries and mapping them to additional SettingsPage indices, without changing the top-level container structure.
  • Localization: labels passed into button factories should be localized at call sites (e.g., via _()).
Published on:
Last updated on: