/ 
Chandra-0.24
/ Chandra

NAME

Chandra - Perl bindings to webview-c for creating cross-platform GUIs

SYNOPSIS

use Chandra;

# Simple one-liner
Chandra->new(
    title  => 'My App',
    url    => 'https://example.com',
    width  => 800,
    height => 600,
)->run;

# Advanced usage with event loop control
my $app = Chandra->new(
    title    => 'My App',
    url      => 'data:text/html,<h1>Hello from Perl!</h1>',
    debug    => 1,
    callback => sub {
        my ($arg) = @_;
        print "JS called: $arg\n";
    },
);

$app->init;

while ($app->loop(1) == 0) {
    # Event loop
}

$app->exit;

DESCRIPTION

This module provides Perl bindings to the webview-c library, allowing you to create cross-platform GUI applications using web technologies (HTML, CSS, JS).

Supported platforms:

  • macOS (WebKit/WKWebView)

  • Linux (WebKitGTK)

  • Windows (Edge/WebView2 with MSHTML fallback)

Windows WebView2 Requirements

On Windows, Chandra uses the modern Edge/WebView2 (Chromium-based) browser component when available, with automatic fallback to the legacy MSHTML (IE11-era) component.

For best results, ensure the WebView2 Runtime is installed:

If WebView2 is not available, Chandra falls back to MSHTML (Internet Explorer rendering engine), which has limited modern web feature support.

See:

  • examples/bind_example.pl — JavaScript to Perl function binding

  • examples/counter_app.pl — counter app with bidirectional communication

For the high-level application wrapper see Chandra::App.

METHODS

new(%args)

Create a new Chandra webview instance.

my $wv = Chandra->new(
    title    => 'My App',
    url      => 'data:text/html,<h1>Hello</h1>',
    width    => 800,
    height   => 600,
    resizable => 1,
    debug    => 0,
    callback => sub { my ($arg) = @_; ... },
);

Options:

title

Window title (default: 'Chandra').

url

Initial URL or data URI (default: 'about:blank').

width

Window width in pixels (default: 800).

height

Window height in pixels (default: 600).

resizable

Allow window resizing (default: 1).

debug

Enable developer tools (default: 0).

callback

Perl coderef called when JavaScript invokes window.external.invoke($arg).

run()

Simple blocking run — shows the window and blocks until it is closed.

init()

Initialize the webview for manual event loop control. Must be called before loop(). Injects the Chandra bridge JavaScript automatically.

loop($blocking)

Process one iteration of the event loop. $blocking is 1 (default) for a blocking wait or 0 for a non-blocking poll. Returns non-zero when the window has been closed and the loop should stop.

eval_js($javascript)

Execute a JavaScript string in the webview. Returns 0 on success.

dispatch_eval_js($javascript)

Schedule JavaScript evaluation via webview_dispatch. Safe to call from inside Perl callbacks invoked from the webview thread.

bind($name, $coderef)

Register a Perl subroutine callable from JavaScript via window.chandra.invoke($name, [args]). Returns $self for chaining.

set_title($title)

Change the window title. Returns $self.

resize($width, $height)

Set the window size.

inject_css($css)

Inject a CSS stylesheet into the current page. Returns 0 on success.

set_fullscreen($enable)

Enter (1) or leave (0) fullscreen mode.

set_color($r, $g, $b, $a)

Set the webview background colour as RGBA values (0-255).

terminate()

Signal the event loop to stop.

exit()

Clean up and close the webview.

title()

Return the current window title.

url()

Return the current URL.

width()

Return the window width in pixels.

height()

Return the window height in pixels.

resizable()

Return whether the window is resizable (1 or 0).

debug()

Return whether debug/developer-tools mode is enabled (1 or 0).

AUTHOR

LNATION <email@lnation.org>

SEE ALSO

Chandra::App, Chandra::Element, Chandra::Bind

LICENSE

MIT License

1 POD Error

The following errors were encountered while parsing the POD:

Around line 95:

Non-ASCII character seen before =encoding in '—'. Assuming UTF-8