Azula
Lightweight GPU accelerated HTML GUI for native JavaScript
Install / Use
/learn @maierfelix/AzulaREADME
azula is a lightweight alternative to Electron. It is based on Ultralight, which is an embedding friendly Fork of WebKit, with less memory usage and low disk space requirements.
azula can optionally run in OSR mode, which makes it easy to embed azula in existing Projects like Game/VR Engines.
Characteristics
| | Azula | Electron | | :--- | :--- | :--- | | CPU | 1.2% | 4.2% | | RAM | 37Mb | 64Mb | | DISK | 31Mb | 118Mb |
Platforms
azula comes with pre-built N-API binaries for the following platforms:
| OS | Status | | ------------- | ------------- | | <img src="https://i.imgur.com/FF3Ssp6.png" alt="" height="16px"> Windows | ✔ | | <img src="https://i.imgur.com/bkBCY7V.png" alt="" height="16px"> Linux | In Progress | | <img src="https://i.imgur.com/iPt4GHz.png" alt="" height="16px"> MacOS | In Progress |
Getting Started
Install azula using:
npm install azula
You can now import azula into your project:
const azula = require("azula");
Or with ESM:
import azula from "azula";
API
Window
When creating a new Window, the following parameters are available:
| Name | Type | Description | | :--- | :--- | :--- | | width (Optional) | Number | The initial width of the window | | height (Optional) | Number | The initial height of the window | | title (Optional) | String | The initial title of the window | | useOffscreenRendering (Optional) | Boolean | When true, creates the window in OSR mode |
let window = new azula.Window({
width: 480,
height: 320,
title: "My App",
useOffscreenRendering: false
});
General
Window.prototype.title
| Type | Description | | :--- | :--- | | String | A getter/setter allowing to retrieve or update the title of the window |
window.title = "My App";
window.title; // "My App"
Window.prototype.width
| Type | Description | | :--- | :--- | | Number | A getter/setter allowing to retrieve or update the width of the window |
window.width = 640;
window.width; // 640
Window.prototype.height
| Type | Description | | :--- | :--- | | Number | A getter/setter allowing to retrieve or update the height of the window |
window.height = 480;
window.height; // 480
Window.prototype.update
This method should be called to poll window events (making the window interactive). In non-OSR mode, this method also does the painting of the window.
window.update();
Window.prototype.flush
This method should only be used in OSR mode. Calling this method executes all remaining render operations and flushes the underlying context.
window.flush();
Window.prototype.shouldClose
| Type | Description | | :--- | :--- | | Boolean | A boolean, indicating if the window should be closed |
window.shouldClose(); // true/false
Loading
Window.prototype.loadHTML
| Name | Type | Description | | :--- | :--- | :--- | | html | String | String representation of the HTML to load |
window.loadHTML("<button>Hello World!</button>");
Window.prototype.loadFile
| Name | Type | Description | | :--- | :--- | :--- | | path | String | The path from where the content gets read from |
window.loadFile("./index.html");
Events
Window.prototype.onresize
| Type | Description | | :--- | :--- | | Function | The function to call when the window gets resized |
The callback's Event parameter has the following structure:
| Name | Type | Description | | :--- | :--- | :--- | | width | Number | The new width of the window | | height | Number | The new height of the window |
window.onresize = e => {
console.log(e.width, e.height);
};
Window.prototype.oncursorchange
| Type | Description | | :--- | :--- | | Function | The function to call when the cursor should be changed |
The callback's Event parameter has the following structure:
| Name | Type | Description | | :--- | :--- | :--- | | name | String | A name representing the cursor type to change to |
window.oncursorchange = e => {
console.log(e.name);
};
Window.prototype.onconsolemessage
| Type | Description | | :--- | :--- | | Function | The function to call when a console message got sent |
The underlying JavaScript engine of azula is WebKit's JavaScriptCore engine. Now this means, that the JavaScript running in the GUI is separated from the JavaScript in Node. When the JavaScript in the GUI makes a call to the console, e.g. console.log(42);, we have to route this call over to Node.
The callback's Event parameter has the following structure:
| Name | Type | Description | | :--- | :--- | :--- | | level | String | The level of the console call. For example "log", "warn" or "error" | | callee | Function | Node's equivalent console function to call | | message | String | The message passed to the console call | | source | String | The file or location where the call was made. Is empty when loadHTML was used | | location | Object | An Object describing the exact code location where the console call was made from |
The location Object comes with the following structure:
| Name | Type | Description | | :--- | :--- | :--- | | line | Number | The code line where the console call originated from | | column | Number | The code column where the console call originated from |
window.onconsolemessage = e => {
let location = `at ${e.source ? e.source + ":" : ""}${e.location.line}:${e.location.column}`;
e.callee.apply(console, [e.message, location]);
};
Event Dispatching
The Event Dispatching System should only be used in OSR mode. Event Dispatching allows to manually send events to the GUI, such as mouse gestures or key events.
Window.prototype.dispatchMouseEvent
| Name | Type | Description | | :--- | :--- | :--- | | type | String | The type of event | | x | Number | The horizontal position of the mouse | | y | Number | The vertical position of the mouse | | button | Number | The currently pressed mouse button |
The following event types are available:
| Name | Type | | :--- | :--- | | onmousedown | Simulating a mouse press action | | onmouseup | Simulating a mouse leave action | | onmousemove | Simulating a mouse move action |
window.dispatchMouseEvent("onmousedown", 16, 32, 1); // press the left mouse button at 16:32
window.dispatchMouseEvent("onmouseup", 16, 32, 1); // leave the left mouse button at 16:32
window.dispatchMouseEvent("onmousemove", 16, 32, 0); // move the mouse to 16:32 without pressing a mouse button
Window.prototype.dispatchKeyEvent
Key Codes are mapped towards GLFW's Key Codes.
| Name | Type | Description | | :--- | :--- | :--- | | type | String | The type of event | | keyCode | Number | A key code representing which key to press |
The following event types are available:
| Name | Type | | :--- | :--- | | onkeydown | Simulating a key press action | | onkeyup | Simulating a key leave action |
window.dispatchKeyEvent("onkeydown", x); // press a key
window.dispatchKeyEvent("onkeyup", x); // leave a key
Window.prototype.dispatchScrollEvent
| Name | Type | Description | | :--- | :--- | :--- | | type | String | The type of event | | deltaX | Number | The horizontal amount to scroll | | deltaY | Number | The vertical amount to scroll |
The following event types are available:
| Name | Type | | :--- | :--- | | onmousewheel | Simulating a mouse wheel action |
window.dispatchScrollEvent("onmousewheel", 0, 1); // scroll upwards, vertically by 1
window.dispatchScrollEvent("onmousewheel", -1, 0); // scroll downwards, horizontally by -1
Object Messaging
The underlying JavaScript engine of azula is WebKit's [JavaScriptCore](https://developer.apple.com/document
