// SPDX-License-Identifier: MIT
#pragma once

#include <gtk/gtk.h>

#include <cstddef>
#include <functional>
#include <string>

namespace udpscope {

/// The About dialog: the app icon, version, commit, build timestamp and where the session
/// files live. An `AdwAboutDialog`, so it is modal on `parent` by being presented on it, and
/// it is an `AdwDialog` rather than a `GtkWindow`. `session_path` is this run's own session
/// file; it goes on the Troubleshooting page, which has a copy button.
void show_about(GtkWindow* parent, const std::string& session_path);

/// The icon name the open About dialog carries, or "" when it is not open. The probe reads it
/// so the dialog is asserted to *show* the app icon rather than merely to open.
const char* about_icon_name();

/// Opens the installed Mallard manual in the desktop help viewer — Yelp, through the
/// `help:` URI the freedesktop Help System Specification defines — rather than drawing a
/// window of our own. `parent` is the window the launch is attributed to (and the one an
/// error is reported on); the viewer is a separate process, so nothing here can be closed
/// with `close_help_windows()`.
///
/// `done`, when the caller gives one, is called with the *launch*'s outcome: whether the
/// `help:` URI was handed to a viewer, and the error text when it was not. It says nothing
/// about the viewer itself — that process may fail for its own reasons and this side cannot
/// see them — so it is the self-check's reading of the path and not a promise that a window
/// appeared. The failure alert is shown either way; the callback is an extra, not instead.
void show_help(GtkWindow* parent, std::function<void(bool ok, const std::string& error)> done = {});

/// Where `help:<id>` resolves to on this system: the first of `$XDG_DATA_HOME/help/<lang>/<id>/`
/// and `$XDG_DATA_DIRS/help/<lang>/<id>/` that holds an `index.page`, or an empty string when no
/// such directory does. This is the specification's own resolution, and the distinction a launch
/// failure turns on: a missing *document* (install it) and a missing *handler* (install a viewer)
/// are different problems with different fixes, and only the file system can tell them apart.
std::string help_installed_path();

/// What UDPSCOPE_PROBE_HELP_MS reports about the manual *in the tree*. `topics` is the
/// number of `<id>.page` files other than `index.page`, and `index` says whether
/// `index.page` is present: the manual is now a set of files on disk (installed by the
/// `install()` rule, and read by Yelp), not a GResource in the binary, so the self-check
/// asserts the set is *there* and must be read as a file-system finding — `topics=0
/// index=0` means the manual is missing from `UDPSCOPE_HELP_DIR`.
struct HelpReport {
  int topics = 0;
  bool index = false;
  int figures = 0;
};

/// Scans the manual's directory without opening a viewer. Safe to call headless.
HelpReport help_self_check();

/// The shortcut overview: the application accelerators and the plot's own interactions,
/// in the sections the tables name. An AdwShortcutsDialog, because GtkShortcutsWindow is
/// deprecated as of GTK 4.18 and this project builds warning-free.
void show_shortcuts(GtkWindow* parent);

/// Closes whichever of the two dialogs are open. Both are `AdwDialog`s, which are not
/// `GtkWindow`s: they close with `adw_dialog_close()`, which emits `::closed`, and the
/// file-scope pointer is nulled by the handler that prevents a second open presenting a dead
/// widget. There is no help window left to close -- the manual opens in a separate viewer
/// process. Used by the probe.
void close_help_windows();

}  // namespace udpscope