NAME

Chandra::Splash - Splash screen / loading state for Chandra applications

SYNOPSIS

use Chandra::Splash;

# Simple splash with default progress template
my $splash = Chandra::Splash->new(
    title    => 'My App',
    width    => 400,
    height   => 200,
    progress => 1,
);

$splash->show;
$splash->update_status('Loading configuration...');
$splash->update_progress(25);

load_config();
$splash->update_status('Connecting...');
$splash->update_progress(75);

connect_db();
$splash->update_progress(100);
$splash->close;

# Custom HTML content
my $splash = Chandra::Splash->new(
    width   => 500,
    height  => 300,
    content => '<h1 style="text-align:center">Welcome</h1>',
);

# Auto-dismiss after 3 seconds
my $splash = Chandra::Splash->new(
    content => '<h1>Starting...</h1>',
    timeout => 3000,
);

# Frameless image splash
my $splash = Chandra::Splash->new(
    image     => 'splash.png',
    width     => 600,
    height    => 400,
    frameless => 1,
);

# Via Chandra::App
my $app = Chandra::App->new(title => 'My App');

my $splash = $app->splash(
    progress => 1,
    init     => sub {
        my ($s) = @_;
        $s->update_status('Loading...'); load_config();
        $s->update_status('Ready!');     $s->update_progress(100);
    },
);

DESCRIPTION

Chandra::Splash creates a lightweight webview window suitable for use as a loading/splash screen while your application initialises. It is built on the same child-window infrastructure as Chandra::Window so all content is rendered via the system's WebView engine.

The window is centred on screen, always-on-top by default, and destroyed cleanly when close() is called. Progress bar and status text can be updated live via JavaScript eval without blocking the main thread.

CONSTRUCTOR

new(%args)

Create a new Splash object (window is not yet shown).

title => STR

Window title and default heading in the built-in template. Defaults to "Loading".

width => INT

Window width in pixels. Defaults to 400.

height => INT

Window height in pixels. Defaults to 200.

frameless => BOOL

Remove window chrome (title bar, close button). Defaults to 0.

progress => BOOL

When true and no content is given, render the built-in splash template with a progress bar and status text area. Defaults to 0.

content => STR

Custom HTML string to display. Takes precedence over progress.

image => STR

Path to an image file (PNG, JPEG, GIF, WebP). The image is base64-encoded and embedded in a frameless-friendly template. Takes precedence over content and progress.

timeout => INT

Milliseconds after which the splash auto-closes. 0 (default) means no automatic close. Note: on macOS the close happens via the next run-loop tick so the caller should still call $splash->close if they want immediate effect.

METHODS

show()

Display the splash window. Returns $self for chaining. Calling show more than once is a no-op.

update_status($text)

Update the status text line in the built-in template. Non-blocking — uses evaluateJavaScript under the hood. Returns $self.

update_progress($percent)

Update the progress bar to $percent (0–100; clamped automatically). Returns $self.

close()

Destroy the splash window.

is_open()

Returns 1 if the native window still exists, 0 otherwise.

wid()

Returns the internal native window id (useful for low-level debugging). Returns -1 before show() or after close().

eval_js($js)

Evaluate arbitrary JavaScript in the splash window. Escape hatch for custom content animations etc.

INTEGRATION WITH Chandra::App

$app->splash(%args) is a convenience wrapper that:

1. Creates and shows a Chandra::Splash.

2. Calls the init coderef (if given) with the splash object.

3. Closes the splash.

4. Returns the (closed) splash object.

$app->splash(
    progress => 1,
    init     => sub {
        my ($splash) = @_;
        do_slow_work();
        $splash->update_progress(100);
    },
);

SEE ALSO

Chandra::App, Chandra::Window

cpanm Chandra

perl -MCPAN -e shell
install Chandra