StyleProvider.hpp

1. Overview

The StyleProvider.hpp header defines the global styling interface for BastionGuard’s GTKmm (GTK4) user interface. It exposes a shared Gtk::CssProvider instance and a helper function used to load and apply application-wide CSS rules.

Functionally, this component provides:

  • A globally accessible CSS provider for GTK widgets
  • Centralized loading of UI style definitions
  • Consistent theming across all application windows and pages
  • Separation of presentation (CSS) from UI logic

2. Dependencies and Includes

#include <gtkmm/cssprovider.h>
  • gtkmm/cssprovider.h – GTKmm interface for loading and applying CSS stylesheets

3. Global Declarations and Scope

extern Glib::RefPtr<Gtk::CssProvider> global_css;

Declares a globally accessible reference-counted CSS provider. The actual instance is defined in the corresponding implementation file and shared across the application.

This design allows any UI component to attach or update styling rules without duplicating providers.

4. Public Interface

4.1 Global Style Loader

void load_style();

Loads the application’s global stylesheet and registers it with the GTK style context. This function is typically invoked during application startup, before creating major UI components.

  • Initializes global_css if not already created
  • Loads CSS rules from embedded resources or external files (implementation-defined)
  • Applies the provider to the default display or screen

5. UI Components

This header does not define widgets. It provides infrastructure used by all UI components to maintain a unified visual style.

6. Internal State and Data Model

No internal state is defined directly in this header. The primary shared object is global_css, which is managed in the implementation file.

7. Usage Context

Typical usage involves calling load_style() during application initialization, followed by automatic propagation of styles to all subsequently created GTK widgets.

int main(int argc, char** argv) {
    load_style();
    // initialize application UI
}

8. Internal Logic

Although implementation details are not visible in this header, a typical load_style() workflow includes:

  • Creation of a Gtk::CssProvider instance
  • Loading CSS content from files, resources, or embedded strings
  • Registering the provider with the GTK style context at application priority
  • Error handling for malformed or missing CSS resources

9. Auto-Update (Scheduled Refresh)

This component does not implement automatic refresh. If runtime style reloading is required, load_style() may be invoked again or extended to support hot-reload mechanisms.

10. Settings Storage

Style configuration is not persisted via JSON or user settings. Styles are typically stored as static resource files (e.g., .css) bundled with the application.

11. Helper Functions and Resource Layout

The location of CSS resources is implementation-defined. A typical layout may resemble:

/usr/share/BastionGuard/themes/default.css
~/.local/share/BastionGuard/themes/custom.css

Custom overrides may optionally be layered on top of default styles.

12. Runtime and Security Considerations

  • Global scope: because global_css is globally accessible, updates should be coordinated to avoid unintended visual side effects.
  • Validation: malformed CSS can break widget rendering; loading should include basic error handling and fallback styles.
  • Performance: reloading styles at runtime may trigger full UI redraws and should be used sparingly.
  • Trust boundary: if user-provided CSS is supported, it must be sanitized and loaded from trusted locations to prevent resource abuse.
Published on:
Last updated on: