Introduction

The GSplash module provides a lightweight splash-screen mechanism for GUI-capable runs. When GUI mode is enabled, a splash image is displayed and informational messages can be overlaid as the application starts.

The main entry points are:

The factory method create() that returns a GSplash instance (or nullptr when GUI is disabled).
The message utilities message() and messageAfter().

Ownership and lifecycle

A GSplash object is created via create() and returned as a std::unique_ptr, which clearly expresses exclusive ownership. When GUI mode is disabled (option --gui off), create() returns nullptr and the caller can proceed without any GUI dependencies.

Internally, the splash widget is managed as a std::unique_ptr to QSplashScreen. If image loading fails, the splash screen is not created and the object remains in an inactive state where message calls become no-ops.

Architecture

Design notes

Image selection supports both filesystem paths and Qt resource lookup: first a direct load is attempted, then the same name is tried as ":/<name>".
If the special image token NOSPLASHIMAGESELECTED is used, the image path is read from the environment variable GSPLASH.
Message updates pump the GUI event loop briefly via QCoreApplication::processEvents to keep the splash responsive while the application is still initializing.

Available Options and their usage

This module reads the following option keys from the runtime option provider:

gui
- Type: boolean (switch)
- Meaning: enable GUI initialization path
- Behavior:
  - when false, GSplash::create() returns nullptr and all message calls are no-ops
  - when true, GSplash::create() attempts to create and show the splash screen
- Note: this switch is defined by GOptions(argc,argv,...) and is globally available.

Module verbosity

GSplash uses the standard logging infrastructure (classes derived from glogger through the base facilities). The effective verbosity is controlled by the logger configuration associated with GSPLASH_LOGGER.

Verbosity level 0 typically prints high-level lifecycle messages (startup, major milestones).
Verbosity level 1 typically prints additional configuration details (selected image source, GUI mode decisions).
Verbosity level 2 typically prints fine-grained progress information.
Debug output prints diagnostic details useful when investigating issues, such as image lookup fallbacks and event-loop timing behavior.

Examples

The module includes example code that demonstrates GUI and CLI execution paths.

gsplash_example : Minimal example showing GSplash creation, message overlay, and timed shutdown.

Example snippet:

auto gsplash = GSplash::create(gopts, "example.png");
gsplash->message("Some text I want to show");
gsplash->messageAfter(500, "Some other text I want to show");