slint-ui 0.3.4 → 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/native/Cargo.toml

@@ -3,7 +3,7 @@
 
 [package]
 name = "slint-node"
-version = "0.3.4"
+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.4"}
-i-slint-core = { version = "=0.3.4"}
-slint-interpreter = { version = "=0.3.4",  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.4",
+    "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"
     }
-}
+}