-
Notifications
You must be signed in to change notification settings - Fork 644
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Refactor JavaScript example to use template project (#4758)
* Refactor JavaScript example to use template project * Feedback * Update docs/tutorial/node/src/getting_started.md Co-authored-by: Simon Hausmann <simon.hausmann@slint.dev>
- Loading branch information
1 parent
2355234
commit 203259f
Showing
13 changed files
with
153 additions
and
123 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,12 +1,14 @@ | ||
<!-- Copyright © SixtyFPS GmbH <info@slint.dev> ; SPDX-License-Identifier: MIT --> | ||
|
||
# Conclusion | ||
|
||
In this tutorial, we have demonstrated how to combine some built-in Slint elements with JavaScript code to build a little | ||
game. There are many more features that we haven't talked about, such as layouts, widgets, or styling. | ||
This tutorial showed you how to combine built-in Slint elements with Rust code to build a | ||
game. There is much more to Slint, such as layouts, widgets, or styling. | ||
|
||
We recommend the following links to continue: | ||
|
||
* [Examples](https://github.com/slint-ui/slint/tree/master/examples): In the Slint repository we have collected a few demos and examples. These are a great starting point to learn how to use many Slint features. | ||
* [Todo Example](https://github.com/slint-ui/slint/tree/master/examples/todo): This is one of the examples that implements a classic use-case. | ||
* [Memory Puzzle](https://github.com/slint-ui/slint/tree/master/examples/memory): This is a slightly more polished version of the code in this example. And you can <a href="https://slint.dev/demos/memory/" target="_blank">play the wasm version</a> in your browser. | ||
* [Slint API Docs](https://slint.dev/docs/node/): The reference documentation for the NodeJS library. | ||
- [Examples](https://github.com/slint-ui/slint/tree/master/examples): In the Slint repository we have collected several demos and examples. These are a great starting point to learn how to use many Slint features. | ||
- [Todo Example](https://github.com/slint-ui/slint/tree/master/examples/todo): This is one of the examples that implements a classic use-case. | ||
- [Memory Puzzle](https://github.com/slint-ui/slint/tree/master/examples/memory): This is a slightly more polished version of the code in this example and you can <a href="https://slint.dev/demos/memory/" target="_blank">play the wasm version</a> in your browser. | ||
- [Slint API Docs](https://slint.dev/docs/rust/slint/): The reference documentation for the main Rust crate. | ||
- [Slint Interpreter API Docs](https://slint.dev/docs/rust/slint_interpreter/): The reference documentation for Rust crate that allows you to dynamically load Slint files. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,20 +1,25 @@ | ||
<!-- Copyright © SixtyFPS GmbH <info@slint.dev> ; SPDX-License-Identifier: MIT --> | ||
|
||
# Creating The Tiles From JavaScript | ||
|
||
What we'll do is take the list of tiles declared in the .slint language, duplicate it, and shuffle it. | ||
We'll do so by accessing the `memory_tiles` property through the JavaScript code - in our case `memory_tiles`. | ||
Since `memory_tiles` is an array in the `.slint` language, it's represented as a JavaScript [`Array`](https://slint.dev/docs/node/). | ||
We can't modify the model generated by the .slint, but we can extract the tiles from it, and put it | ||
This step places the game tiles randomly. | ||
|
||
The code takes the list of tiles, duplicates it, and shuffles it, accessing the `memory_tiles` property through the JavaScript code. | ||
|
||
As `memory_tiles` is an array, it's represented as a JavaScript [`Array`](https://slint.dev/docs/node/). | ||
You can't change the model generated by Slint, but you can extract the tiles from it, and put them | ||
in a [`slint.ArrayModel`](https://slint.dev/docs/node/classes/arraymodel.html) which implements the [`Model`](https://slint.dev/docs/node/interfaces/model.html) interface. | ||
`ArrayModel` allows us to make modifications and we can use it to replace the static generated model. | ||
`ArrayModel` allows you to make changes and you can use it to replace the static generated model. | ||
|
||
We modify `main.js` like so: | ||
Change `main.js` to the following: | ||
|
||
```js | ||
{{#include main_tiles_from_js.js:main}} | ||
``` | ||
|
||
Running this gives us a window on the screen that now shows a 4 by 4 grid of rectangles, which can show or obscure | ||
the icons when clicking. There's only one last aspect missing now, the rules for the game. | ||
Running this code opens a window that now shows a 4 by 4 grid of rectangles, which show or hide | ||
the icons when a player clicks on them. | ||
|
||
There's one last aspect missing now, the rules for the game. | ||
|
||
<video autoplay loop muted playsinline src="https://slint.dev/blog/memory-game-tutorial/creating-the-tiles-from-rust.mp4"></video> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,34 +1,40 @@ | ||
<!-- Copyright © SixtyFPS GmbH <info@slint.dev> ; SPDX-License-Identifier: MIT --> | ||
|
||
# From One To Multiple Tiles | ||
|
||
After modeling a single tile, let's create a grid of them. For the grid to be our game board, we need two features: | ||
After modeling a single tile, this step creates a grid of them. For the grid to be a game board, you need two features: | ||
|
||
1. **A data model**: An array created as a Rust model, where each element describes the tile data structure, such as: | ||
|
||
- URL of the image | ||
- Whether the image is visible | ||
- If the player has solved this tile. | ||
|
||
2. A way of creating multiple instances of the tiles. | ||
|
||
1. A data model: This shall be an array where each element describes the tile data structure, such as the | ||
url of the image, whether the image shall be visible and if this tile has been solved. We modify the model | ||
from JS code. | ||
2. A way of creating many instances of the tiles, with the above `.slint` markup code. | ||
With Slint you declare an array of structures based on a model using square brackets. Use a <span class="hljs-keyword">for</span> loop | ||
to create multiple instances of the same element. | ||
|
||
In Slint we can declare an array of structures using brackets, to create a model. We can use the <span class="hljs-keyword">for</span> loop | ||
to create many instances of the same element. In `.slint` the for loop is declarative and automatically updates when | ||
the model changes. We instantiate all the different <span class="hljs-title">MemoryTile</span> elements and place them on a grid based on their | ||
index with a little bit of spacing between the tiles. | ||
With Slint the for loop is declarative and automatically updates when | ||
the model changes. The loop instantiates all the <span class="hljs-title">MemoryTile</span> elements and places them on a grid based on their | ||
index with spacing between the tiles. | ||
|
||
First, we copy the tile data structure definition and paste it at top inside the `memory.slint` file: | ||
First, add the tile data structure definition at the top of the `memory.slint` file: | ||
|
||
```slint | ||
{{#include ../../rust/src/main_multiple_tiles.rs:tile_data}} | ||
``` | ||
|
||
Next, we replace the _export component <span class="hljs-title">MainWindow</span> inherits Window { ... }_ section at the bottom of the `memory.slint` file with the following snippet: | ||
Next, replace the _export component <span class="hljs-title">MainWindow</span> inherits Window { ... }_ section at the bottom of the `memory.slint` file with the following: | ||
|
||
```slint | ||
{{#include ../../rust/src/main_multiple_tiles.rs:main_window}} | ||
``` | ||
|
||
The <code><span class="hljs-keyword">for</span> tile\[i\] <span class="hljs-keyword">in</span> memory_tiles:</code> syntax declares a variable `tile` which contains the data of one element from the `memory_tiles` array, | ||
and a variable `i` which is the index of the tile. We use the `i` index to calculate the position of tile based on its row and column, | ||
using the modulo and integer division to create a 4 by 4 grid. | ||
and a variable `i` which is the index of the tile. The code uses the `i` index to calculate the position of a tile, based on its row and column, | ||
using modulo and integer division to create a 4 by 4 grid. | ||
|
||
Running this gives us a window that shows 8 tiles, which can be opened individually. | ||
Running the code opens a window that shows 8 tiles, which a player can open individually. | ||
|
||
<video autoplay loop muted playsinline src="https://slint.dev/blog/memory-game-tutorial/from-one-to-multiple-tiles.mp4"></video> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,39 +1,42 @@ | ||
<!-- Copyright © SixtyFPS GmbH <info@slint.dev> ; SPDX-License-Identifier: MIT --> | ||
|
||
# Game Logic In JavaScript | ||
|
||
We'll implement the rules of the game in JavaScript as well. The general philosophy of Slint is that merely the user | ||
interface is implemented in the `.slint` language and the business logic in your favorite programming | ||
language. The game rules shall enforce that at most two tiles have their curtain open. If the tiles match, then we | ||
consider them solved and they remain open. Otherwise we wait for a little while, so the player can memorize | ||
the location of the icons, and then close them again. | ||
This step implements the rules of the game in Rust as well. | ||
|
||
Slint's general philosophy is that you implement the user interface in Slint and the business logic in your favorite programming | ||
language. | ||
|
||
The game rules enforce that at most two tiles have their curtain open. If the tiles match, then the game | ||
considers them solved and they remain open. Otherwise, the game waits briefly so the player can memorize | ||
the location of the icons, and then closes the curtains again. | ||
|
||
We'll modify the `.slint` markup in the `memory.slint` file to signal to the JavaScript code when the user clicks on a tile. | ||
Two changes to <span class="hljs-title">MainWindow</span> are needed: We need to add a way for the MainWindow to call to the JavaScript code that it should | ||
check if a pair of tiles has been solved. And we need to add a property that JavaScript code can toggle to disable further | ||
tile interaction, to prevent the player from opening more tiles than allowed. No cheating allowed! First, we paste | ||
the callback and property declarations into <span class="hljs-title">MainWindow</span>: | ||
Change the contents of `memory.slint` to signal to the JavaScript code when the user clicks on a tile. | ||
|
||
```slint | ||
{{#include ../../rust/src/main_game_logic_in_rust.rs:mainwindow_interface}} | ||
``` | ||
|
||
The last change to the `.slint` markup is to act when the <span class="hljs-title">MemoryTile</span> signals that it was clicked on. | ||
We add the following handler in <span class="hljs-title">MainWindow</span>: | ||
This change adds a way for the <span class="hljs-title">MainWindow</span> to call to the JavaScript code that it should | ||
check if a player has solved a pair of tiles. The Rust code needs an additional property to toggle to disable further | ||
tile interaction, to prevent the player from opening more tiles than allowed. No cheating allowed! | ||
|
||
The last change to the code is to act when the <span class="hljs-title">MemoryTile</span> signals that a player clicked it. | ||
|
||
Add the following handler in <span class="hljs-title">MainWindow</span>: | ||
|
||
```slint | ||
{{#include ../../rust/src/main_game_logic_in_rust.rs:tile_click_logic}} | ||
``` | ||
|
||
On the JavaScript side, we can now add an handler to the `check_if_pair_solved` callback, that will check if | ||
two tiles are opened. If they match, the `solved` property is set to true in the model. If they don't | ||
match, start a timer that will close them after one second. While the timer is running, we disable every tile so | ||
one can't click anything during this time. | ||
On the JavaScript side, now add a handler to the `check_if_pair_solved` callback, that checks if a player opened two tiles. If they match, the code sets the `solved` property to true in the model. If they don't | ||
match, start a timer that closes the tiles after one second. While the timer is running, disable every tile so | ||
a player can't click anything during this time. | ||
|
||
Insert this code before the `mainWindow.run()` call: | ||
|
||
```js | ||
{{#include main_game_logic.js:game_logic}} | ||
``` | ||
|
||
These were the last changes and running the result gives us a window on the screen that allows us | ||
to play the game by the rules. | ||
These were the last changes and running the code opens a window that allows a player to play the game by the rules. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,48 +1,42 @@ | ||
<!-- Copyright © SixtyFPS GmbH <info@slint.dev> ; SPDX-License-Identifier: MIT --> | ||
|
||
# Getting Started | ||
|
||
In this tutorial, we use JavaScript as the host programming language. We also support other programming languages like | ||
This tutorial uses JavaScript as the host programming language. Slint also supports other programming languages like | ||
[Rust](https://slint.dev/docs/rust/slint/) or [C++](https://slint.dev/docs/cpp/). | ||
|
||
You'll need a development environment with [Node.js 16](https://nodejs.org/download/release/v16.19.1/) and [npm](https://www.npmjs.com/) installed. More recent | ||
versions of NodeJS are currently not supported, for details check [Issue #961](https://github.com/slint-ui/slint/issues/961). | ||
Since Slint is implemented in the Rust programming language, you also need to install a Rust compiler (1.70 or newer). You can easily install a Rust compiler | ||
following the instruction from [the Rust website](https://www.rust-lang.org/learn/get-started). | ||
You will also need some additional platform-specific dependencies, see <https://github.com/slint-ui/slint/blob/master/docs/building.md#prerequisites> | ||
Slint has an application template you can use to create a project with dependencies already set up that follows recommended best practices. | ||
|
||
We're going to use `slint-ui` as `npm` dependency. | ||
|
||
In a new directory, we create a new `package.json` file. | ||
Clone the template with the following command: | ||
|
||
```json | ||
{{#include package.json}} | ||
```sh | ||
git clone https://github.com/slint-ui/slint-nodejs-template memory | ||
cd memory | ||
``` | ||
|
||
This should look familiar to people familiar with NodeJS. We see that this package.json | ||
references a `main.js`, which we will add later. We must then create, in the same directory, | ||
the `memory.slint` file. Let's just fill it with a hello world for now: | ||
Install dependencies with npm: | ||
|
||
```slint | ||
{{#include memory.slint:main_window}} | ||
```sh | ||
npm install | ||
``` | ||
|
||
What's still missing is the `main.js`: | ||
The `package.json` file references `src/main.js` as the entry point for the application and `src/main.js` references `memory.slint` as the UI file. | ||
|
||
Replace the contents of `src/main.js` with the following: | ||
|
||
```js | ||
{{#include main_initial.js:main}} | ||
``` | ||
|
||
To recap, we now have a directory with a `package.json`, `memory.slint`, and `main.js`. | ||
Note that `slint.loadFile` resolves files from the process's current working directory, so from the `package.json` file's location. | ||
|
||
We can now compile and run the program: | ||
Replace the contents of `ui/appwindow.slint` with the following: | ||
|
||
```sh | ||
npm install | ||
npm start | ||
```slint | ||
{{#include memory.slint:main_window}} | ||
``` | ||
|
||
and a window will appear with the green "Hello World" greeting. | ||
|
||
 | ||
Run the example with `npm start` and a window appears with the green "Hello World" greeting. | ||
|
||
Feel free to use your favorite IDE for this purpose. | ||
 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,15 +1,16 @@ | ||
<!-- Copyright © SixtyFPS GmbH <info@slint.dev> ; SPDX-License-Identifier: MIT --> | ||
|
||
# Introduction | ||
|
||
This tutorial will introduce you to the Slint UI framework in a playful way by implementing a little memory game. We're going to combine the `.slint` language for the graphics with the game rules implemented in JavaScript. | ||
This tutorial introduces you to the Slint UI framework in a playful way by implementing a memory game. It combines the `.slint` language for the graphics with the game rules implemented in Rust. | ||
|
||
The game consists of a grid of 16 rectangular tiles. Clicking on a tile uncovers an icon underneath. | ||
We know that there are 8 different icons in total, so each tile has a sibling somewhere in the grid with the | ||
same icon. The objective is to locate all icon pairs. You can uncover two tiles at the same time. If they | ||
aren't the same, the icons will be obscured again. | ||
If you uncover two tiles with the same icon, then they remain visible - they're solved. | ||
There are 8 different icons in total, so each tile has a sibling somewhere in the grid with the | ||
same icon. The objective is to locate all icon pairs. The player can uncover two tiles at the same time. If they | ||
aren't the same, the game obscures the icons again. | ||
If the player uncovers two tiles with the same icon, then they remain visible - they're solved. | ||
|
||
This is how the game looks like in action: | ||
This is how the game looks in action: | ||
|
||
<video autoplay loop muted playsinline src="https://slint.dev/blog/memory-game-tutorial/memory_clip.mp4" | ||
class="img-fluid img-thumbnail rounded"></video> | ||
class="img-fluid img-thumbnail rounded"></video> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.