GtkHelper

1. Overview

The GtkHelper module provides GTK construction and dialog utilities for BastionGuard Backup. It provides reusable GTK event, busy-state, dialog, input, notebook, list, label, checkbox, spin-button, and button helpers used by the graphical interface.

The implementation is written in Vala and uses GLib/GIO together with the application utility namespaces required by the file.

2. Dependencies and Integration

The module imports:

  • TeeJee.Logging
  • TeeJee.FileSystem
  • TeeJee.JsonHelper
  • TeeJee.ProcessHelper
  • TeeJee.System
  • TeeJee.Misc
  • Gtk

Key runtime integrations include:

  • GTK – graphical widgets, dialogs, images, event processing, or window lifecycle

3. Declared Types

3.1 TeeJee.GtkHelper

namespace TeeJee.GtkHelper

This namespace groups stateless utility functions and shared constants.

4. State, Properties, Constants, and Signals

The file does not maintain mutable object state. Its primary content is constants or stateless helper behavior.

5. Public API and Operational Methods

5.1 gtk_do_events()

public void gtk_do_events ()

Implements the gtk do events operation for this module.

5.2 gtk_set_busy()

public void gtk_set_busy (bool busy, Gtk.Window win)

Implements the gtk set busy operation for this module.

  • Interacts with GTK/VTE objects and must execute UI changes on the graphical main context.

5.3 gtk_messagebox()

public static void gtk_messagebox(string title, string message, Gtk.Window? parent_win, bool is_error = false)

Implements the gtk messagebox operation for this module.

  • Interacts with GTK/VTE objects and must execute UI changes on the graphical main context.

5.4 gtk_inputbox()

public string? gtk_inputbox(string title, string message, Gtk.Window? parent_win, bool mask_password = false)

Implements the gtk inputbox operation for this module.

  • Interacts with GTK/VTE objects and must execute UI changes on the graphical main context.
  • Processes credential-related values that should remain protected in memory and logs.

5.5 wait_and_close_window()

public void wait_and_close_window(int milliseconds, Gtk.Window window)

Implements the wait and close window operation for this module.

  • Interacts with GTK/VTE objects and must execute UI changes on the graphical main context.
  • Contains a polling loop with an explicit sleep interval.

5.6 gtk_dialog_run()

public int gtk_dialog_run(Gtk.Dialog dlg)

Implements the gtk dialog run operation for this module.

  • Interacts with GTK/VTE objects and must execute UI changes on the graphical main context.

5.7 gtk_combobox_set_value()

public bool gtk_combobox_set_value (Gtk.ComboBoxText combo, int index, string val)

Implements the gtk combobox set value operation for this module.

5.8 gtk_combobox_get_value()

public string gtk_combobox_get_value (Gtk.ComboBoxText combo, int index, string default_value)

Implements the gtk combobox get value operation for this module.

5.9 add_notebook()

public static Gtk.Stack add_notebook(Gtk.Box box, bool show_tabs = true, bool show_border = true)

Creates or appends notebook to the relevant GTK container, collection, or system configuration.

  • Interacts with GTK/VTE objects and must execute UI changes on the graphical main context.

5.10 add_treeview()

public static Gtk.ListBox add_treeview(Gtk.Box box, Gtk.SelectionMode selection_mode = Gtk.SelectionMode.SINGLE)

Creates or appends treeview to the relevant GTK container, collection, or system configuration.

  • Interacts with GTK/VTE objects and must execute UI changes on the graphical main context.

5.11 add_column_text()

public static Gtk.Label add_column_text(Gtk.ListBox listbox, string title, out Gtk.Label cell)

Creates or appends column text to the relevant GTK container, collection, or system configuration.

  • Interacts with GTK/VTE objects and must execute UI changes on the graphical main context.

5.12 add_column_icon_radio_text()

public static Gtk.Box add_column_icon_radio_text(Gtk.ListBox listbox, string title, out Gtk.Image cell_pix, out Gtk.CheckButton cell_radio, out Gtk.Label cell_text)

Creates or appends column icon radio text to the relevant GTK container, collection, or system configuration.

  • Interacts with GTK/VTE objects and must execute UI changes on the graphical main context.

5.13 add_label_scrolled()

public static Gtk.Label add_label_scrolled(Gtk.Box box, string text, bool show_border = false, bool wrap = false, int ellipsize_chars = 40)

Creates or appends label scrolled to the relevant GTK container, collection, or system configuration.

  • Interacts with GTK/VTE objects and must execute UI changes on the graphical main context.

5.14 format_text()

public static string format_text(string text, bool bold = false, bool italic = false, bool large = false)

Builds a human-readable representation from the current object state.

5.15 add_label_header()

public static Gtk.Label add_label_header(Gtk.Box box, string text, bool large_heading = false)

Creates or appends label header to the relevant GTK container, collection, or system configuration.

5.16 add_checkbox()

public static Gtk.CheckButton add_checkbox(Gtk.Box box, string text)

Creates or appends checkbox to the relevant GTK container, collection, or system configuration.

  • Interacts with GTK/VTE objects and must execute UI changes on the graphical main context.

5.17 add_spin()

public static Gtk.SpinButton add_spin(Gtk.Box box, double min, double max, double val, int digits = 0, double step = 1, double step_page = 1)

Creates or appends spin to the relevant GTK container, collection, or system configuration.

  • Interacts with GTK/VTE objects and must execute UI changes on the graphical main context.

5.18 add_button()

public static Gtk.Button add_button(Gtk.Box box, string text, string tooltip, Gtk.SizeGroup? size_group, Gtk.Image? icon = null)

Creates or appends button to the relevant GTK container, collection, or system configuration.

  • Interacts with GTK/VTE objects and must execute UI changes on the graphical main context.

5.19 add_button_box()

public static Gtk.Box add_button_box(Gtk.Box box, Gtk.Orientation orientation = Gtk.Orientation.HORIZONTAL, Gtk.Align halign = Gtk.Align.CENTER, int spacing = 6)

Creates or appends button box to the relevant GTK container, collection, or system configuration.

  • Interacts with GTK/VTE objects and must execute UI changes on the graphical main context.

6. Internal Helpers

6.1 add_label()

private Gtk.Label add_label(Gtk.Box box, string text, bool bold = false, bool italic = false, bool large = false)

Creates or appends label to the relevant GTK container, collection, or system configuration.

7. Operational Flow

  1. Transform raw values, command output, or metadata into structured or display-ready form.
  2. Apply the requested operation and update runtime or persistent state.

8. Error Handling and Diagnostics

  • Boolean, nullable, or empty-string return values communicate recoverable failures to callers.

9. Runtime and Security Considerations

  • Sensitive data: credentials and passphrases should not be logged or persisted without protected storage and restrictive permissions.
  • Polling: synchronous wait loops can delay shutdown or block the caller when the underlying operation does not complete.
  • Shared state: static caches and global switches are shared by all callers and are not automatically thread-isolated.
  • GTK lifecycle: widgets and local main loops require a valid graphical context and careful close/destroy handling.

10. Licensing

The source is distributed under the license terms declared in the source header.

Published on:
Last updated on: