Introduction

kwui is a gui toolkit for creating graphical user interfaces. It works on Windows, and Android. kwui is released under the terms of the GNU Lesser General Public License, which allows for flexible licensing of client applications. kwui is inspired by rust-sciter, that use JavaScript and CSS to describe the UI, and Rust for business logic.

The kwui toolkit contains “widgets”: GUI components such as buttons, text input, or windows.

kwui depends the following libraries:

• Skia: Skia is a 2D graphics library with support for multiple output devices. More information available on the Skia website.
• Direct2D: Direct2D is a 2D graphics library for windows platform.
• QuickJS: QuickJS is a small and embeddable JavaScript engine.

kwui is divided into three parts:

• kwui-rs: kwui-rs is the Rust binding to the C++ kwui-sys library.

  • Provides simple and type-safe API.
  • Integrate with cargo crates ecosystem.

• kwui-sys: kwui-sys is written in C++. It inter-operates with underline operating system, render the user interface, and handle user input events. It's pretty complex, some features:

  • Renderer: Direct2D or Skia
  • Layout and style: CSS
  • Scripting: builtin JavaScript engine with JSX extension support.
  • Data model: React Hooks alike JavaScript functional components.
  • Platform-dependent resource system

• kwui-cli: kwui-cli is a command line tool.

  • Create project template.
  • Package application resources.
  • Provide build assistance for Windows and Android target platform.

Quick Start

kwui supports Windows host only, targeting Windows and Android.

NOTE: Linux and OpenHarmony(OHOS) support in the future.

Installation

1. Install the Rust development environments.
2. Install kwui-cli tool.

   #![allow(unused)]
   fn main() {
   cargo install kwui-cli
   }

First project

Let's create a hello world project my_proj:

1. Create project from template.

   # Creates a new Rust project 'my_proj' under current directory
   kwui new my_proj
   cd my_proj
   

2. Build and run.

   cargo run
   

NOTE

kwui is using prebuilt library to accelerate the build process.

If your access to GitHub is difficult or slow, set the environment variable to use a mirror:

KWUI_BINARIES_URL=https://gitee.com/wanghoi/kwui-binaries/releases/download/{tag}/kwui-binaries-{key}.tar.gz
KWUI_TEMPLATES_URL=https://gitee.com/wanghoi/kwui-binaries/releases/download/{tag}/kwui-templates-{key}.tar.gz

Porting to Android

1. Prepare the Android development environment.
2. Build the project for Android.

   # Build 'app-debug.apk'
   kwui build apk
   

3. Install the resulting APK to your phone.

   NOTE: only supports arm64-v8a abi now.

Initializing kwui

Library initialization and main loop

Before using kwui, you need to initialize it with Application::new(); this connects to the operation system, sets up the locale and performs other initialization tasks. Application::quit() exits the application.

Like most GUI toolkits, kwui uses an event-driven programming model. When the application is doing nothing, kwui sits in the “main loop” and waits for input. If the user performs some action - say, a mouse click - then the main loop “wakes up” and delivers an event to kwui. kwui forwards the event to one or more elements in the gui Scene Tree.

User interface elements and input event callbacks are defined in JavaScript modules. After initialize kwui, you ScriptEngine::load_file(path) to load and run the root JavaScript entry script.

When elements receive an event, they frequently emit one or more “event callbacks”. Event callbacks calls into JavaScript function callback, that “something interesting happened”.

When your callbacks in JavaScript are invoked, you would typically take some action - for example, when an Open button is clicked you might update application states or perform some tasks with side effects. After a callback finishes, kwui will return to the main loop and await more user input.

Business code is written in Rust to perform network requests, and native operations. ScriptEngine is the bridge between Rust and JavaScript.

The main() function for a simple kwui application:

// src/main.rs
use kwui::{Application, ScriptEngine};

pub fn main() {
    // initialize kwui
    let app = Application::new();
    
    // set resource directory to local folder
    app.set_resource_root_dir(concat!(
        env!("CARGO_MANIFEST_DIR"),
        "/assets"
    ));
    
    // load 'assets/entry.js'
    ScriptEngine::load_file(":/entry.js");

    // run event loop
    app.exec();
}

JavaScript in kwui

Entrypoint

assets/entry.js

kwui ScriptEngine load and run the JavaScript entry file: assets/entry.js. It shows a Dialog with parameters, such as dialog window width, height, and script module path of gui root component.

app.showDialog({
	title: "Hello kwui",
    width: 1280,
    height: 720,
	modulePath: "./hello.js"
});

assets/hello.js

assets/hello.js export the builder function, which invoked by kwui, to build root gui component and stylesheet on-demand.

// JSX syntax to define root component
function Hello(props, kids) {
	return <div style="margin: 16px;">
		<span id="hello">Hello kwui</span>
	</div>;
}

// `css` is a builtin JavaScript template literal, to define CSS-in-JS
var hello_css = css`
#hello {
    color: orangered;
}
`;

// root script module need to export the `builder` function
export function builder(moduleParams) {
	return {
		root: <Hello />,
		stylesheet: hello_css,
	}
}

Dialog

A dialog window is a top-level window mostly used for present graphics visuals and brief communications with the user.

app.showDialog()

let dialogId = app.showDialog({
	title: "Hello kwui",
    width: 1280,
    height: 720,
	modulePath: "./hello.js"
});

Create and show a new dialog window on Windows, replace root view content on Android.

app.closeDialog()

Close the specific dialog on Windows, on effects on Android.

app.closeDialog(this.dialogId);

Component Hooks

useState()

import { useState, useContext, createContext } from "Keact";

export function UseStateExample(props) {
	let [n, setN] = useState(0);
	return <button onclick={() => setN(n + 1)}>{`Click ${n} times`}</button>;
}

export function builder() {
	return {
		root: <UseStateExample></UseStateExample>,
		stylesheet: css`
button { margin: 10px; padding: 4px; background-color: orange; }
button.dark { background-color: black; color: white; }
button:hover { background-color: orangered; }
`
	};
}

useEffect()

import { useState, useEffect } from "Keact";

export function UseEffectExample(props) {
	let [n, setN] = useState(0);
	useEffect(() => {
		console.log("useEffect setup, n:", n);
		return () => console.log("useEffect cleanup, n:", n);
	}, [n]);
	return <button onclick={() => setN(n + 1)}>{`Click ${n} times`}</button>;
}

export function builder() {
	return {
		root: <UseEffectExample></UseEffectExample>,
		stylesheet: css`
button { margin: 10px; padding: 4px; background-color: orange; }
button.dark { background-color: black; color: white; }
button:hover { background-color: orangered; }
`
	}
}

useContext()

import { useState, useContext, createContext } from "Keact";

let [Theme, ThemeProvider] = createContext();

function Sub1(props, kids) {
	return kids;
}

function Sub2(props, kids) {
	let theme = useContext(Theme);
	return <button class={theme}>Hello</button>
}

function ThemeExample() {
	return <ThemeProvider value="dark">
		<Sub1>
			<Sub2></Sub2>
		</Sub1>
	</ThemeProvider>
}

export function builder() {
	return { root: <ThemeExample /> };
}

Context properties

In component function, you can access creation context, from this object.

• this.dialogId - the current dialog id where the Component is located.

Composite Pattern

Primitive Elements

Text

function ExampleTextComponent() {
    return (<p id="text-container">
        anonymous text span
        <span id="simple-text">simple text span</span>
        <span>{"escaped text: \u{f111}\u{f192}"}</span>
    </p>);
}
var textStyle = css`
#text-container {
    text-align: center;
}
#simple-text {
    color: blue;
    font-size: 24px;
}

Image

function ImageComponent() {
    return <div id="img_a"></div>;
}
var imageStyle = css`
#id {
    width: 32px;
    height: 32px;
    background-image: url(':/sample.png');
}
`;

Button

function ButtonComponent(props, kids) {
    return <button onclick={() => console.log("clicked")}>Button</button>;
}
var buttonStyle = css`
button { margin: 10px; padding: 4px; background-color: orange; }
button:hover { background-color: orangered; }
`;

LineEdit

function LineEditComponent(props, kids) {
    return <line_edit id="line-edit" value="abc"></line_edit>;
}
var buttonStyle = css`
#line-edit {
	display: inline-block;
	width: 200px;
	height: 32px;
}`;

Rust and JavaScript Interop

Basic sample

use kwui::{Application, ScriptEngine, ScriptValue};

pub fn main() {
    let app = Application::new();
    
    // set resource directory to local folder
    app.set_resource_root_dir(concat!(
        env!("CARGO_MANIFEST_DIR"),
        "/assets"
    ));
    
    // load 'assets/entry.js'
    ScriptEngine::load_file(":/entry.js");

    // call JavaScript `function add(a, b) -> sum` from Rust
    let sum = ScriptEngine::call_global_function("script_add", &[
        ScriptValue::new_int(1),
        ScriptValue::new_int(2),
    ]).to_int();

    // export Rust function to JavaScript
    ScriptEngine::add_global_function("rust_add", rust_add);

    // run event loop
    app.exec();
}

fn rust_add(a: i32, b: i32) -> i32 {
    a + b
}

// call Rust function from JavaScript
console.log("sum:", rust_add(1, 2));

References

Rust API documentation

CSS in kwui

kwui has a builtin CSS parser and layout engine, implements a subset of CSS 2.2 Visual Formatting Model.

Supported CSS attributes

• position: static, relative, absolute
• display: none, inline, inline-block, block
• margin-*, border-*, padding-*
• width, height
• background-color, background-image
• border-radius
• color
• text-align, line-height, vertical-align
• line-height

Supported CSS selectors

• tag, class, id: div {}, .class1 {}, #id
• combinators: div span {}, div + span {}, p, span {}

Style Scoped

Full, scoped and component-friendly CSS support for JSX, inspired by styled-jsx.

• Locally-scoped styles
• Co-location
• JavaScript variables in styles

function StyleComponent(props) {
   return (<div class="style-root">
        <style jsx>{`
            div.style-root {
                font-size: 24px;
            }
            span {
                color: blue;
            }
        `}</style>
        <span>blue text</span>
    </div>);
}

kwui provide native support for scoped style. When your components render, static styles are cached for better performance. CSS reparse only occurs when you are using JavaScript variables in styles.

Note: scoped style feature was added in v0.3.0.

Android Support

kwui has experimental android support now.

Requirements

kwui is targeting Android 11 (API level 30) or higher, and build for arm64-v8a target ABI now. Android Emulator and ChromeOS are not supported yet.

Prepare Android development environment

1. Install latest Android Studio
2. Install latest Android SDK and NDK from Android Studio's SDKManager.
3. Set the system environment variable, Example:

ANDROID_HOME=D:/projects/Android/Sdk
ANDROID_NDK_HOME=D:/projects/Android/Sdk/ndk/27.0.11718014
CARGO_TARGET_AARCH64_LINUX_ANDROID_LINKER=%ANDROID_NDK_HOME%/toolchains/llvm/prebuilt/windows-x86_64/bin/aarch64-linux-android30-clang.cmd
JAVA_HOME=D:/Program Files/Android/Android Studio/jbr

Build android apk

Enter the project directory, which is created by the kwui-cli tool.

cd test_proj
kwui build apk

Gallery

kwui has been used by many of author's internal projects, with many custom gui elements addons.

VoIP Test tool

Remote Desktop

Installer

Android examples

Common Questions

1. Why not Electron?

   • Try new technology on mobile platforms quickly.
   • Shorter development trial-and-error cycle.

2. What's the future plan?

   • Add Rust api to create custom rendering gui elements.
   • Better documentation.
   • More test cases.
   • Improve CSS support.
   • OpenHarmony(OHOS) support.

QuickJS VM

QuickJS is a small and embeddable Javascript engine. It supports most of the ES2023 specification including modules, asynchronous generators, proxies and operator overloading.

kwui is using QuickJS to define user interface structure, and responds to user input events.

Features

• Small and easily embeddable stack based VM.
• Fast interpreter with very low startup time.
• Garbage collection using reference counting.
• Small built-in standard library.
• With simplified Rust API.

Compiling JavaScript

QuickJS compiles JavaScript to VM bytecode, with 3 passes:

1. Parse JavaScript to generate initial bytecode.
2. Resolve scoped variables to local or free variable references.
3. Resolve and back patch jump offsets, peephole optimization.

JSValue Representation

JSValue is a Javascript value which can be a primitive type (such as Number, String, ...) or an Object.

kwui is compiling QuickJS with strict nan-boxing, for the purpose of cross-platform compatibility. JSValue is 64-bit on 32-bit and 64-bit platforms.

JSValue Format

QuickJS number is double-precision floating-point number. double type is 64-bit, comprised of 1 sign bit, 11 exponent bits and 52 mantissa bits.

   7         6        5        4        3        2        1        0
seeeeeee|eeeemmmm|mmmmmmmm|mmmmmmmm|mmmmmmmm|mmmmmmmm|mmmmmmmm|mmmmmmmm

JSValue store non-NaN float with all bits binary reversed, therefore the first 12 bits are non-zero.

NaN numbers, and other primitive types, are represented by tag and value.

00000000|0000tttt|vvvvvvvv|vvvvvvvv|vvvvvvvv|vvvvvvvv|vvvvvvvv|vvvvvvvv
12-bits zero |tag|  48-bit placeholder for values: pointers, strings

Reference counted JSValue type (such as object, string, symbol), the most significant bit of tag is 1.

QuickJS Opcodes

ByteCode Compatibilities

The bytecode compatibilities of QuickJS VM, depends on macro defines.

We are compiling QuickJS with:

// #undef CONFIG_ATOMICS
// #undef CONFIG_BIGNUM
// #undef CONFIG_DEBUGGER
#define SHORT_OPCODES 1

• Atomics support disabled.
• Big number extension disabled.
• Debugger opcodes disabled.
• Extra short opcodes enabled.

ByteCode Module Format

After the JavaScript module file is compiled, the module's bytecode can be serialized, and loaded later.

Lexical-scope child functions are serialized recursively as parent function's constants.

Notation

• multi-bytes values are serialized in little endian order.
• ATOM - interned string - when serialization, converted to zero started index.
• xB - length is x bytes
• LEB128 - Little Endian Base 128 – length is a variable-length encoding format designed to store arbitrarily large integers in a small number of bytes. There are two variations: unsigned LEB128 and signed LEB128. These vary slightly, so a user program that wants to decode LEB128 values would explictly choose the appropriate unsigned or signed methods.
• STRING - string length, followed by utf-8 or utf1-16 string data

Compiled Module Specification

• The compiled script module contains:

  1B: version
  LEB128: number of atoms
      [STRING][STRING][STRING] : an array of atom strings
  MODULE: script module
      FUNCTION - module root function
  

• STRING

  LEB128: for utf-8 string, `length << 1`, for utf-16 string, `(length << 2) + 1`
  [1B] or [2B]: utf-8 or utf-16 string data
  

• ATOM

  LEB128: for intger atom, `(atom << 1) | 1`, for string atom, converted to `(first_atom + index) << 1`
  

• MODULE

  1B: module tag, hex `0x0f`
  ATOM: module name
  LEB128: number of requested module entries
      [ATOM]: requested module name
  LEB128: number of exported module entries
      [LOCAL_EXPORT] or [INDIRECT_EXPORT]: local variable/function export or indirect export
  LEB128: number of star exported module entries
      [LEB128]: star exported module indexes
  LEB128: number of imported module entries
      [IMPORT]: imported modules
  

• FUNCTION

  1B: function tag, hex `0x0e`
  2B: flag, from lsb to msb:
      1b: has_prototype
      1b: has_simple_paramter_list
      1b: is_derived_class_constructor
      1b: need_home_object
      2b: func_kind
      1b: new_target_allowed
      1b: super_call_allowed
      1b: super_allowed
      1b: arguments_allowed
      1b: has_debug
      1b: backtrace_barrier
      4b: _unused_
  1B: js mode, 1: strict
  ATOM: function name
  LEB128: argument count
  LEB128: variable count
  LEB128: defined argument count
  LEB128: stack size
  LEB128: closure variable count
  LEB128: constant `JS_VALUE` pool count
  LEB128: bytecode length
  LEB128: `(arg_count + var_count)`
  [VAR_DEF]: `(arg_count + var_count)` variable definitions
  [CLOSURE_VAR]: `closure_var_count` closure variable definitions
  FUNCTION_BYTECODES - raw function bytecodes, atoms inside operands and converted to atom indices
  DEBUG_INFO - optional script debug information
  [JS_VALUE] - `cpool_count` - script constant values
  

• DEBUG_INFO

  ATOM - script filename
  LEB128 - script start line number
  LEB128 - `pc2line_len` - size of the opcodes to line number table
      [1B] - `pc2line_buf`
  

• JS_VALUE

  FUNCTION, STRING, OBJECT, or ARRAY
  

ByteCode References

Encoding

Each opcode is encoded by 1-byte opcode type, variable length operands. Each operand is little-endian encoded 1, 2, or 4-bytes length integer.

+--------+---------------------------+
| opcode | operand_1, operator2, ... |
+--------+---------------------------+

Typical operand types:

• index: index into the stack, or some array.
• label: jump label index or offset.
• value: literal value.
• atom: interned string.

Notation

• a, b => a + b indicates that the add opcode takes two items off the stack (a and b) and places the sum of these two values on the stack. The leftmost item (a) is the top of the stack.
• . => a indicates that the push_xxx opcode takes no stack item, and push a new item to the top of stack.
• All stack descriptions elide subsequent items that may be on the stack. It can be assumed that unspecified stack elements do not influence the semantics of an operation, except when a stack overflow would result.
• The stack size is determined when compiling the script function, and all stack items are JSValue.
• Excluding the designated invalid opcode, the QuickJS VM currently implements 245 opcodes, 66 of which are short opcodes indicating the number of operands (push_N, get_locN, put_locN, get_argN, ...).
• Function arguments on stack are in reverse orders, the first argument is pushed to the stack first, therefore the last argument is on the top of the stack.

Live Reload

kwui has a built-in live reload system. It allows you to change your JavaScript user interface source code and view the result in realtime.

Live Reload is currently only available for Windows Debug builds.

Usage

1. Load resource from local directory

   #![allow(unused)]
   fn main() {
   let app = Application::new();
   if cfg!(all(target_os = "windows", debug_assertions)) {
       app.set_resource_root_dir("{your assets dir}");
   }
   }

   Then asset URLs like :/entry.js will be mapped to {your assets dir}/entry.js.

2. While the application is running, pressing F5 to trigger Live Reload of current Dialog, the user interface will be re-built.

   Rust-side states are preserved, JavaScript module-level and component-level variables and states are re-initialized during reload.

How it works

• Increase application's script version.
• Reload entry module script
  • import will also import a new version of dependent JavaScript modules.
• Call builder() to build a new root component tree.
  • Child components in other JavaScript modules are built recursively.
• Patch old user interface with new root component tree.
• Garbage Collection will recycle old JavaScript module states later.