slint-ui 0.3.5 → 1.0.0

package/README.md

@@ -1,4 +1,4 @@
-# Slint-node
+# Slint-node (Beta)
 
 [![npm](https://img.shields.io/npm/v/slint-ui)](https://www.npmjs.com/package/slint-ui)
 
@@ -6,9 +6,12 @@
 Slint-node is the integration with node.
 
 The complete Node documentation can be viewed online at https://slint-ui.com/docs/node/.
+To get started you can use the [Walk-through tutorial](https://slint-ui.com/docs/tutorial/node).
+We also have a [Getting Started Template](https://github.com/slint-ui/slint-nodejs-template) repository with
+the code of a minimal application using Slint that can be used as a starting point to your program.
 
-**Warning: Pre-Alpha**
-Slint is still in the early stages of development: APIs will change and important features are still being developed.
+**Warning: Beta**
+Slint-node is still in the early stages of development: APIs will change and important features are still being developed.
 
 ## Installing Slint
 
@@ -18,6 +21,16 @@ Slint is available via NPM, so you can install by running the following command:
 npm install slint-ui
 ```
 
+### Dependencies
+
+You need to install the following components:
+
+  * **[Node.js](https://nodejs.org/download/release/v16.19.1/)** (v16. Newer versions currently not supported: [#961](https://github.com/slint-ui/slint/issues/961))
+  * **[npm](https://www.npmjs.com/)**
+  * **[Rust compiler](https://www.rust-lang.org/tools/install)** (1.66 or newer)
+
+You will also need a few more dependencies, see <https://github.com/slint-ui/slint/blob/master/docs/building.md#prerequisites>
+
 ## Using Slint
 
 To initialize the API, you first need to import the `slint-ui` module in our code:
@@ -144,4 +157,4 @@ component.model = model;
 model.push(4); // this works
 // does NOT work, getting the model does not return the right object
 // component.model.push(5);
- ```
+```

package/cover.md

@@ -0,0 +1,164 @@
+# Slint-node (Beta)
+
+[![npm](https://img.shields.io/npm/v/slint-ui)](https://www.npmjs.com/package/slint-ui)
+
+[Slint](https://slint-ui.com/) is a UI toolkit that supports different programming languages.
+Slint-node is the integration with node.
+
+To get started you can use the [Walk-through tutorial](https://slint-ui.com/docs/tutorial/node).
+We also have a [Getting Started Template](https://github.com/slint-ui/slint-nodejs-template) repository with
+the code of a minimal application using Slint that can be used as a starting point to your program.
+
+**Warning: Beta**
+Slint-node is still in the early stages of development: APIs will change and important features are still being developed.
+
+## Slint Language Manual
+
+The [Slint language manual](../slint) covers the Slint UI description language
+in detail.
+
+## Installing Slint
+
+Slint is available via NPM, so you can install by running the following command:
+
+```sh
+npm install slint-ui
+```
+
+### Dependencies
+
+You need to install the following components:
+
+  * **[Node.js](https://nodejs.org/download/release/v16.19.1/)** (v16. Newer versions currently not supported: [#961](https://github.com/slint-ui/slint/issues/961))
+  * **[npm](https://www.npmjs.com/)**
+  * **[Rust compiler](https://www.rust-lang.org/tools/install)** (1.66 or newer)
+
+You will also need a few more dependencies, see <https://github.com/slint-ui/slint/blob/master/docs/building.md#prerequisites>
+
+## Using Slint
+
+To initialize the API, you first need to import the `slint-ui` module in our code:
+
+```js
+let slint = require("slint-ui");
+```
+
+This step also installs a hook in NodeJS that allows you to import `.slint` files directly:
+
+```js
+let ui = require("../ui/main.slint");
+```
+
+Combining these two steps leads us to the obligatory "Hello World" example:
+
+```js
+require("slint-ui");
+let ui = require("../ui/main.slint");
+let main = new ui.Main();
+main.run();
+```
+
+See [/examples/todo/node](https://github.com/slint-ui/slint/tree/master/examples/todo/node) for a full example.
+
+## API Overview
+
+### Instantiating a component
+
+The exported component is exposed as a type constructor. The type constructor takes as parameter
+an object which allow to initialize the value of public properties or callbacks.
+
+```js
+require("slint-ui");
+// In this example, the main.slint file exports a module which
+// has a counter property and a clicked callback
+let ui = require("ui/main.slint");
+let component = new ui.MainWindow({
+    counter: 42,
+    clicked: function() { console.log("hello"); }
+});
+```
+
+### Accessing a property
+
+Properties are exposed as properties on the component instance
+
+```js
+component.counter = 42;
+console.log(component.counter);
+```
+
+### Callbacks
+
+The callbacks are also exposed as property that have a setHandler function, and that can can be called.
+
+```js
+// connect to a callback
+component.clicked.setHandler(function() { console.log("hello"); })
+// emit a callback
+component.clicked();
+```
+
+### Type Mappings
+
+| `.slint` Type | JavaScript Type | Notes |
+| --- | --- | --- |
+| `int` | `Number` | |
+| `float` | `Number` | |
+| `string` | `String` | |
+| `color` | `String` | Colors are represented as strings in the form `"#rrggbbaa"`. When setting a color property, any CSS compliant color is accepted as a string. |
+| `length` | `Number` | |
+| `physical_length` | `Number` | |
+| `duration` | `Number` | The number of milliseconds |
+| `angle` | `Number` | The value in degrees |
+| structure | `Object` | Structures are mapped to JavaScrip objects with structure fields mapped to properties. |
+| array | `Array` or Model Object | |
+
+### Models
+
+For property of array type, they can either be set using an array.
+In that case, getting the property also return an array.
+If the array was set within the .slint file, the array can be obtained
+
+```js
+component.model = [1, 2, 3];
+// component.model.push(4); // does not work, because it operate on a copy
+// but re-assigning works
+component.model = component.model.concat(4);
+```
+
+Another option is to set a model object.  A model object has the following function:
+
+* `rowCount()`: returns the number of element in the model.
+* `rowData(index)`: return the row at the given index
+* `setRowData(index, data)`: called when the model need to be changed. `this.notify.rowDataChanged` must be called if successful.
+
+When such an object is set to a model property, it gets a new `notify` object with the following function
+
+* `rowDataChanged(index)`: notify the view that the row was changed.
+* `rowAdded(index, count)`: notify the view that rows were added.
+* `rowRemoved(index, count)`: notify the view that a row were removed.
+* `reset()`: notify the view that everything may have changed.
+
+As an example, here is the implementation of the `ArrayModel` (which is available as `slint.ArrayModel`)
+
+```js
+let array = [1, 2, 3];
+let model = {
+    rowCount() { return a.length; },
+    rowData(row) { return a[row]; },
+    setRowData(row, data) { a[row] = data; this.notify.rowDataChanged(row); },
+    push() {
+        let size = a.length;
+        Array.prototype.push.apply(a, arguments);
+        this.notify.rowAdded(size, arguments.length);
+    },
+    remove(index, size) {
+        let r = a.splice(index, size);
+        this.notify.rowRemoved(size, arguments.length);
+    },
+};
+component.model = model;
+model.push(4); // this works
+// does NOT work, getting the model does not return the right object
+// component.model.push(5);
+```

package/dist/index.d.ts

@@ -0,0 +1,172 @@
+/**
+ * @hidden
+ */
+declare function load_native_lib(): any;
+/**
+ * @hidden
+ */
+declare let native: any;
+/**
+ * @hidden
+ */
+declare class Component {
+    protected comp: any;
+    constructor(comp: any);
+    run(): void;
+    show(): void;
+    hide(): void;
+    get window(): SlintWindow;
+    send_mouse_click(x: number, y: number): void;
+    send_keyboard_string_sequence(s: String): void;
+}
+interface Point {
+    x: number;
+    y: number;
+}
+interface Size {
+    width: number;
+    height: number;
+}
+interface SlintWindow {
+    show(): void;
+    hide(): void;
+    is_visible: boolean;
+    logical_position: Point;
+    physical_position: Point;
+    logical_size: Size;
+    physical_size: Size;
+}
+/**
+ * @hidden
+ */
+declare class WindowAPI implements SlintWindow {
+    protected impl: any;
+    constructor(impl: any);
+    show(): void;
+    hide(): void;
+    get is_visible(): boolean;
+    get logical_position(): Point;
+    set logical_position(pos: Point);
+    get physical_position(): Point;
+    set physical_position(pos: Point);
+    get logical_size(): Size;
+    set logical_size(size: Size);
+    get physical_size(): Size;
+    set physical_size(size: Size);
+}
+/**
+ * @hidden
+ */
+interface Callback {
+    (): any;
+    setHandler(cb: any): void;
+}
+/**
+ * ModelPeer is the interface that the run-time implements. An instance is
+ * set on dynamic Model<T> instances and can be used to notify the run-time
+ * of changes in the structure or data of the model.
+ */
+interface ModelPeer {
+    /**
+     * Call this function from our own model to notify that fields of data
+     * in the specified row have changed.
+     * @argument row
+     */
+    rowDataChanged(row: number): void;
+    /**
+     * Call this function from your own model to notify that one or multiple
+     * rows were added to the model, starting at the specified row.
+     * @param row
+     * @param count
+     */
+    rowAdded(row: number, count: number): void;
+    /**
+     * Call this function from your own model to notify that one or multiple
+     * rows were removed from the model, starting at the specified row.
+     * @param row
+     * @param count
+     */
+    rowRemoved(row: number, count: number): void;
+    /**
+     * Call this function from your own model to notify that the model has been
+     * changed and everything must be reloaded
+     */
+    reset(): void;
+}
+/**
+ * Model<T> is the interface for feeding dynamic data into
+ * `.slint` views.
+ *
+ * A model is organized like a table with rows of data. The
+ * fields of the data type T behave like columns.
+ */
+interface Model<T> {
+    /**
+     * Implementations of this function must return the current number of rows.
+     */
+    rowCount(): number;
+    /**
+     * Implementations of this function must return the data at the specified row.
+     * @param row
+     */
+    rowData(row: number): T;
+    /**
+     * Implementations of this function must store the provided data parameter
+     * in the model at the specified row.
+     * @param row
+     * @param data
+     */
+    setRowData(row: number, data: T): void;
+    /**
+     * This public member is set by the run-time and implementation must use this
+     * to notify the run-time of changes in the model.
+     */
+    notify: ModelPeer;
+}
+/**
+ * @hidden
+ */
+declare class NullPeer implements ModelPeer {
+    rowDataChanged(row: number): void;
+    rowAdded(row: number, count: number): void;
+    rowRemoved(row: number, count: number): void;
+    reset(): void;
+}
+/**
+ * ArrayModel wraps a JavaScript array for use in `.slint` views. The underlying
+ * array can be modified with the [[ArrayModel.push]] and [[ArrayModel.remove]] methods.
+ */
+declare class ArrayModel<T> implements Model<T> {
+    /**
+     * @hidden
+     */
+    private a;
+    notify: ModelPeer;
+    /**
+     * Creates a new ArrayModel.
+     *
+     * @param arr
+     */
+    constructor(arr: Array<T>);
+    rowCount(): number;
+    rowData(row: number): T;
+    setRowData(row: number, data: T): void;
+    /**
+     * Pushes new values to the array that's backing the model and notifies
+     * the run-time about the added rows.
+     * @param values
+     */
+    push(...values: T[]): void;
+    /**
+     * Removes the specified number of element from the array that's backing
+     * the model, starting at the specified index. This is equivalent to calling
+     * Array.slice() on the array and notifying the run-time about the removed
+     * rows.
+     * @param index
+     * @param size
+     */
+    remove(index: number, size: number): void;
+    get length(): number;
+    values(): IterableIterator<T>;
+    entries(): IterableIterator<[number, T]>;
+}

package/dist/index.js

@@ -0,0 +1,184 @@
+"use strict";
+// Copyright © SixtyFPS GmbH <info@slint-ui.com>
+// SPDX-License-Identifier: GPL-3.0-only OR LicenseRef-Slint-commercial
+// Load the native library with `process.dlopen` instead of with `require`.
+// This is only done for autotest that do not require nom or neon_cli to
+// copy the lib to its right place
+/**
+ * @hidden
+ */
+function load_native_lib() {
+    const os = require('os');
+    process.dlopen(module, process.env.SLINT_NODE_NATIVE_LIB, os.constants.dlopen.RTLD_NOW);
+    return module.exports;
+}
+/**
+ * @hidden
+ */
+let native = !process.env.SLINT_NODE_NATIVE_LIB ? require('../native/index.node') : load_native_lib();
+/**
+ * @hidden
+ */
+class Component {
+    constructor(comp) {
+        this.comp = comp;
+    }
+    run() {
+        this.comp.run();
+    }
+    show() {
+        this.window.show();
+    }
+    hide() {
+        this.window.hide();
+    }
+    get window() {
+        return new WindowAPI(this.comp.window());
+    }
+    send_mouse_click(x, y) {
+        this.comp.send_mouse_click(x, y);
+    }
+    send_keyboard_string_sequence(s) {
+        this.comp.send_keyboard_string_sequence(s);
+    }
+}
+/**
+ * @hidden
+ */
+class WindowAPI {
+    constructor(impl) {
+        this.impl = impl;
+    }
+    show() {
+        this.impl.show();
+    }
+    hide() {
+        this.impl.hide();
+    }
+    get is_visible() {
+        return this.impl.get_is_visible();
+    }
+    get logical_position() {
+        return this.impl.get_logical_position();
+    }
+    set logical_position(pos) {
+        this.impl.set_logical_position(pos);
+    }
+    get physical_position() {
+        return this.impl.get_physical_position();
+    }
+    set physical_position(pos) {
+        this.impl.set_physical_position(pos);
+    }
+    get logical_size() {
+        return this.impl.get_logical_size();
+    }
+    set logical_size(size) {
+        this.impl.set_logical_size(size);
+    }
+    get physical_size() {
+        return this.impl.get_physical_size();
+    }
+    set physical_size(size) {
+        this.impl.set_physical_size(size);
+    }
+}
+require.extensions['.60'] = require.extensions['.slint'] =
+    function (module, filename) {
+        var c = native.load(filename);
+        module.exports[c.name().replace(/-/g, '_')] = function (init_properties) {
+            let comp = c.create(init_properties);
+            let ret = new Component(comp);
+            c.properties().forEach((x) => {
+                Object.defineProperty(ret, x.replace(/-/g, '_'), {
+                    get() { return comp.get_property(x); },
+                    set(newValue) { comp.set_property(x, newValue); },
+                    enumerable: true,
+                });
+            });
+            c.callbacks().forEach((x) => {
+                Object.defineProperty(ret, x.replace(/-/g, '_'), {
+                    get() {
+                        let callback = function () { return comp.invoke_callback(x, [...arguments]); };
+                        callback.setHandler = function (callback) { comp.connect_callback(x, callback); };
+                        return callback;
+                    },
+                    enumerable: true,
+                });
+            });
+            return ret;
+        };
+    };
+/**
+ * @hidden
+ */
+class NullPeer {
+    rowDataChanged(row) { }
+    rowAdded(row, count) { }
+    rowRemoved(row, count) { }
+    reset() { }
+}
+/**
+ * ArrayModel wraps a JavaScript array for use in `.slint` views. The underlying
+ * array can be modified with the [[ArrayModel.push]] and [[ArrayModel.remove]] methods.
+ */
+class ArrayModel {
+    /**
+     * Creates a new ArrayModel.
+     *
+     * @param arr
+     */
+    constructor(arr) {
+        this.a = arr;
+        this.notify = new NullPeer();
+    }
+    rowCount() {
+        return this.a.length;
+    }
+    rowData(row) {
+        return this.a[row];
+    }
+    setRowData(row, data) {
+        this.a[row] = data;
+        this.notify.rowDataChanged(row);
+    }
+    /**
+     * Pushes new values to the array that's backing the model and notifies
+     * the run-time about the added rows.
+     * @param values
+     */
+    push(...values) {
+        let size = this.a.length;
+        Array.prototype.push.apply(this.a, values);
+        this.notify.rowAdded(size, arguments.length);
+    }
+    // FIXME: should this be named splice and have the splice api?
+    /**
+     * Removes the specified number of element from the array that's backing
+     * the model, starting at the specified index. This is equivalent to calling
+     * Array.slice() on the array and notifying the run-time about the removed
+     * rows.
+     * @param index
+     * @param size
+     */
+    remove(index, size) {
+        let r = this.a.splice(index, size);
+        this.notify.rowRemoved(index, size);
+    }
+    get length() {
+        return this.a.length;
+    }
+    values() {
+        return this.a.values();
+    }
+    entries() {
+        return this.a.entries();
+    }
+}
+module.exports = {
+    private_api: native,
+    ArrayModel: ArrayModel,
+    Timer: {
+        singleShot: native.singleshot_timer,
+    },
+};

package/native/Cargo.toml

@@ -3,7 +3,7 @@
 
 [package]
 name = "slint-node"
-version = "0.3.5"
+version = "1.0.0"
 authors = ["Slint Developers <info@slint-ui.com>"]
 edition = "2021"
 build = "build.rs"
@@ -20,9 +20,9 @@ crate-type = ["cdylib"]
 name = "slint_node_native"
 
 [dependencies]
-i-slint-compiler = { version = "=0.3.5"}
-i-slint-core = { version = "=0.3.5"}
-slint-interpreter = { version = "=0.3.5",  features = ["display-diagnostics"] }
+i-slint-compiler = { version = "=1.0.0"}
+i-slint-core = { version = "=1.0.0"}
+slint-interpreter = { version = "=1.0.0",  features = ["display-diagnostics"] }
 
 vtable = { version = "0.1.6"}
 
@@ -34,5 +34,8 @@ rand = "0.8"
 scoped-tls-hkt = "0.1"
 spin_on = "0.1" #FIXME: remove and delegate to async JS instead
 
+# Enable image-rs' default features to make all image formats available for nodejs builds
+image = { version = "0.24.0" }
+
 [build-dependencies]
 neon-build = "0.8.0"

package/native/lib.rs

@@ -111,7 +111,7 @@ fn create<'cx>(
     cx: &mut CallContext<'cx, impl neon::object::This>,
     component_type: slint_interpreter::ComponentDefinition,
 ) -> JsResult<'cx, JsValue> {
-    let component = component_type.create();
+    let component = component_type.create().unwrap();
     let persistent_context = persistent_context::PersistentContext::new(cx);
 
     if let Some(args) = cx.argument_opt(0).and_then(|arg| arg.downcast::<JsObject>().ok()) {
@@ -341,7 +341,7 @@ declare_types! {
             let component = cx.borrow(&this, |x| x.0.as_ref().map(|c| c.clone_strong()));
             let component = component.ok_or(()).or_else(|()| cx.throw_error("Invalid type"))?;
             run_scoped(&mut cx,this.downcast().unwrap(), || {
-                component.run();
+                component.run().unwrap();
                 Ok(())
             })?;
             Ok(JsUndefined::new().as_value(&mut cx))
@@ -490,7 +490,7 @@ declare_types! {
             let this = cx.this();
             let window = cx.borrow(&this, |x| x.0.as_ref().cloned());
             let window_adapter = window.ok_or(()).or_else(|()| cx.throw_error("Invalid type"))?;
-            window_adapter.show();
+            window_adapter.show().unwrap();
             Ok(JsUndefined::new().as_value(&mut cx))
         }
 
@@ -498,7 +498,7 @@ declare_types! {
             let this = cx.this();
             let window = cx.borrow(&this, |x| x.0.as_ref().cloned());
             let window_adapter = window.ok_or(()).or_else(|()| cx.throw_error("Invalid type"))?;
-            window_adapter.hide();
+            window_adapter.hide().unwrap();
             Ok(JsUndefined::new().as_value(&mut cx))
         }
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "slint-ui",
-    "version": "0.3.5",
+    "version": "1.0.0",
     "homepage": "https://github.com/slint-ui/slint",
     "license": "SEE LICENSE IN LICENSE.md",
     "repository": {
@@ -17,9 +17,9 @@
     "scripts": {
         "install": "neon build --release && tsc",
         "build": "tsc",
-        "docs": "typedoc lib/index.ts"
+        "docs": "typedoc --hideGenerator --readme cover.md lib/index.ts"
     },
     "devDependencies": {
         "typedoc": "^0.19.2"
     }
-}
+}