LiveScanDialog.hpp

1. Overview

The LiveScanDialog.hpp header defines the LiveScanDialog class, a GTKmm-based dialog window used to present real-time scan output to the user. The component is designed to display progressive feedback from long-running scanning operations, provide cancellation control, and collect full textual output for post-processing or reporting.

Functionally, LiveScanDialog provides:

  • Real-time display of scanner output in a scrollable text view
  • Visual progress indication via a progress bar
  • User-driven cancellation of active scans
  • Thread-safe buffering of background output
  • Aggregation of complete scan logs for later retrieval

2. Dependencies and Includes

#include <gtkmm.h>
#include <atomic>
#include <mutex>
#include <vector>
  • gtkmm.h – GTK4 C++ bindings for windowing and widget management
  • <atomic> – lock-free flags for lifecycle and state management
  • <mutex> – synchronization for buffered output access
  • <vector> – temporary storage for pending output lines

3. Class Declaration and Scope

class LiveScanDialog : public Gtk::Window

The LiveScanDialog class derives from Gtk::Window, making it suitable as a top-level modal or modeless dialog in desktop user interfaces.

4. Construction

4.1 Constructor

LiveScanDialog(Gtk::Window* parent,
               const std::string& path);

Creates a new dialog instance associated with a parent window and bound to a specific filesystem path being scanned.

5. Public Interface

5.1 Output Ingestion

void append_output(const std::string& line);

Appends a new line of scan output. This method is designed to be safely callable from background worker threads. Output is buffered and later flushed to the UI thread.

5.2 Completion Marker

void mark_finished();

Marks the scan as completed. This updates internal state and typically triggers final UI updates (e.g., disabling the cancel button and finalizing progress state).

5.3 Cancellation State

bool cancelled() const;

Returns true if the user has requested cancellation of the scan.

5.4 Output Retrieval

std::string get_full_output() const;

Returns the complete aggregated scan output accumulated during execution.

6. UI Components

Gtk::Box root_;
Gtk::ProgressBar progress_;
Gtk::ScrolledWindow scroller_;
Gtk::TextView text_view_;
Gtk::Button btn_cancel_;
  • root_ – main layout container
  • progress_ – visual indicator of scan progress
  • scroller_ – scrollable container for textual output
  • text_view_ – widget displaying scan logs
  • btn_cancel_ – user control for aborting the scan

7. Concurrency and Internal State

std::atomic<bool> finished_{false};
std::atomic<bool> cancelled_{false};
std::atomic<bool> flush_pending_{false};

mutable std::mutex mtx_;
std::vector<std::string> pending_lines_;
std::string full_output_;
  • finished_ – indicates whether the scan has completed
  • cancelled_ – reflects user-initiated cancellation
  • flush_pending_ – prevents redundant idle flush scheduling
  • mtx_ – protects buffered output and aggregated logs
  • pending_lines_ – temporary buffer for unflushed output
  • full_output_ – cumulative scan output storage

8. UI Synchronization Strategy

8.1 Idle Flush Handler

void flush_output_idle();

Flushes buffered output from pending_lines_ into the GTK text view. This method is typically scheduled on the GTK main loop using an idle handler, ensuring that UI updates occur on the correct thread.

9. Execution Workflow

A typical scan session follows this pattern:

  • Dialog is constructed and displayed
  • Background scanner emits output via append_output()
  • Output is buffered and periodically flushed to the UI thread
  • User may cancel via btn_cancel_
  • Scanner invokes mark_finished() on completion
  • Final output is made available through get_full_output()

10. Security and Reliability Considerations

  • Thread affinity: all GTK widget modifications must occur on the main thread; the idle flush mechanism enforces this constraint
  • Output sanitization: untrusted scan output should be sanitized before display if it may contain control characters or markup
  • Cancellation semantics: background workers must periodically check cancelled() to ensure timely termination
  • Memory usage: full_output_ grows unbounded; consider truncation or external storage for very large scans
  • UI responsiveness: excessive flush frequency may degrade performance; batching via pending_lines_ mitigates this risk
  • Graceful shutdown: ensure that background tasks complete or abort before destroying the dialog to avoid dangling callbacks
Published on:
Last updated on: