Donate Module (DonatePage)

1. Overview

The Donate module provides a dedicated UI page that encourages voluntary support for BastionGuard and offers a single-click action to open an external donation URL using the system’s default browser handler.

The implementation is a GTKmm (GTK4) widget derived from Gtk::Box and focuses on a simple, non-intrusive layout: title, explanatory text, a branded image, and a call-to-action button.

2. User Interface Structure

2.1 Main Container

DonatePage is built as a vertical container:

  • Gtk::Box(Gtk::Orientation::VERTICAL, 12) to ensure consistent spacing
  • set_margin(20) to provide comfortable page padding

2.2 Title Section

The title is rendered using a centered markup label:

  • Gtk::Label with set_use_markup(true)
  • Text: <b>Sostieni BastionGuard</b> (localized via _())
  • Alignment: Gtk::Align::CENTER

2.3 Descriptive Text

A multi-line localized description explains the voluntary nature of donations and the purpose of support. The label is configured for readability:

  • set_wrap(true) to allow multi-line rendering
  • set_justify(Gtk::Justification::CENTER) for centered paragraph layout
  • set_margin(10) to separate it from surrounding elements

2.4 Donation Image

The page includes a branded image (e.g., PayPal/Donate banner) displayed with Gtk::Picture. The image is loaded from the application resources:

picture->set_file(Gio::File::create_for_path(resource("donate.png")));

Presentation behavior:

  • set_content_fit(Gtk::ContentFit::CONTAIN) to preserve proportions
  • set_size_request(350, 121) to constrain the visual footprint
  • Centered alignment via set_halign() and set_valign()
  • Additional spacing via set_margin(10)

If the resource cannot be loaded, the module logs a localized diagnostic message to stderr, without failing the page construction (graceful degradation).

2.5 Call-to-Action Button

The donation action is exposed through a centered GTK button with an icon + label composition:

  • Internal content is a Gtk::Box(Gtk::Orientation::HORIZONTAL, 6)
  • Gtk::Image using the icon name emblem-favorite (heart-style emblem)
  • Gtk::Label with localized text: Vai alla donazione
  • Gtk::Button uses set_child(*btn_box) and is horizontally centered

The button click is connected to the handler DonatePage::on_open_donate().

3. Runtime Behavior

3.1 Donation Link Opening

When the user clicks the button, the module delegates opening the donation page to the OS default URI handler:

Gio::AppInfo::launch_default_for_uri("https://www.paypal.com/donate/?hosted_button_id=XR4622XJZMKGN");

This approach avoids embedding any browser component and respects the user’s system settings and sandboxing policies.

3.2 Error Handling

The URI launch is protected by a try/catch block for Glib::Error. On failure, a localized error string is written to stderr including the exception reason:

  • Examples include missing default handler, sandbox restrictions, or system policy blocks

4. Security and Privacy Considerations

  • No sensitive data handling: the module only displays static text/media and opens a URL.
  • External navigation: the donation page is opened via the system browser handler; BastionGuard does not intercept traffic.
  • Graceful degradation: missing image assets do not prevent the page from functioning.
  • Localization readiness: user-facing strings are wrapped with _() for gettext translation.
Published on:
Last updated on: