From c24a51aabac64d562b68abeb3ee02ec84ea16f9e Mon Sep 17 00:00:00 2001 From: Olivier Goffart Date: Mon, 4 Apr 2022 21:10:06 +0200 Subject: [PATCH] Apply suggestions from code review grammar and wording fixes Co-authored-by: Simon Hausmann --- docs/recipes/recipes.md | 68 ++++++++++++++++++++--------------------- 1 file changed, 33 insertions(+), 35 deletions(-) diff --git a/docs/recipes/recipes.md b/docs/recipes/recipes.md index 3e795e0b3..5a4c26c40 100644 --- a/docs/recipes/recipes.md +++ b/docs/recipes/recipes.md @@ -21,31 +21,30 @@ export Recipe := Window { } ``` -In that first example, we see the basics of the Slint language. +In this first example, you see the basics of the Slint language: - - We import the widgets `VerticalBox` and `Button` from the standard widgets library - using the `import` statement. That statement can import widgets or your own component + - The `VerticalBox` layout and the `Button` widget is imported from the standard library + using the `import` statement. That statement can import widgets or your own components declared in different files. Built-in element such as `Window` or `Rectangle` do not need to be imported. - - We declare the `Recipe` component using `:=`. That component is a `Window` and it contains + - The `Recipe` component is declared using `:=`. It is a `Window` and it contains a layout (`VerticalBox`) with one button. - - The elements are just instantiated with their name and braces. They form a tree of elements. - They can optionaly be named using `:=` + - The elements are just instantiated with their name and braces; they form a tree. + They can optionally be named using `:=` - Elements can have properties and can be set with `:`. In this case the `Button` has a `text` property and it is assigned a binding that computes a string by concatenating some string literals, and the `counter` property. - - You can declare custom properties with `property <...>`. Property need to have a type and can have - a default value. This is how we declare the `counter` property in this example. - - In addition to properties, element can also have callback. In this case we assigned a callback + - You can declare custom properties with `property <...>`. A property needs to have a type and can have + a default value. This is how the `counter` property is declared in this example. + - In addition to properties, elements can also have callback. In this case we assign a callback handler to the `clicked` callback of the button with `=> { ... }` - - Properties are automatically re-evaluated once a dependency changes. The `text` binding of + - Property bindings are automatically re-evaluated if any of the properties the binding depends on changes. The `text` binding of the button is going to be automatically re-computed when the `counter` is changed. ### React to a Button in native code -Instead of having code in the slint language to increment the counter, we will now do the same -in native code. +This example increments the counter using native code, instead with the slint language. ```slint import { VerticalBox, Button } from "std-widgets.slint"; @@ -60,17 +59,18 @@ export Recipe := Window { } ``` -We create a callback `button-pressed` and using the `<=>` syntax, we bind it to the `button.clicked`. +The `button-pressed` callback is declared using the `<=>` syntax, which binds it to the `button.clicked` signal. -Properties and callback declared on the root element of the main component will be exposed to the -native code. Note that `-` is replaced by `_`. In slint, `-` and `_` are equivalent and interchangable. -But this since `-` is not valid in identifier in native code, they are replaced by `_`. +Properties and callbacks declared on the root element of the main component will be exposed to the +native code. + +Note that `-` is replaced by `_`. In slint, `-` and `_` are equivalent and interchangable. But this since `-` is not valid in identifier in native code, they are replaced by `_`.
Rust code -For technical reason in this example, we use `import {Recipe}` in the `slint!` macro, but -in real code, you can put the whole slint code in the `slint!` macro, or use a buyild script. +For technical reasons, this example uses `import {Recipe}` in the `slint!` macro, but +in real code, you can put the whole slint code in the `slint!` macro, or use a build script. ```rust,no_run @@ -90,13 +90,12 @@ fn main() { ``` A `struct Recipe` is generated by Slint. For each property, a getter (`get_counter`) and a setter (`set_counter`) -is generated. For the callback, a function to set the callback is generated (`on_button_pressed`) +is generated. For the callback, a function to set the callback is generated (`on_button_pressed`). -The `Recipe` struct implements the [`slint::ComponentHandle`] trait. A component handle is an equivalent of `Rc`, -It is a handle to a Component which has a strong and a weak reference count. We call the `as_weak` function to -get a weak handle to the component which we can move into the callback. -We can't move a strong component because that would form a cycle. (The Component has ownership of the callback -which itself has ownership of its capture) +The `Recipe` struct implements the [`slint::ComponentHandle`] trait. A component handle is an equivalent of `Rc`. +It is a handle to a component with a strong and a weak reference count. We call the `as_weak` function to +get a weak handle to the component, which we can move into the callback. +We can't move a strong handle because that would form a cycle: The component handle has ownership of the callback, which itself has ownership of the closure's captured variables.
@@ -118,8 +117,8 @@ int main(int argc, char **argv) } ``` -Some simple boiler place needs to be done with cmake for the integration, so that the Slint compiler -generates the button_native.h header file from the Slint file. It contains the generated`class Recipe`. +Some simple boiler plate needs to be done with cmake for the integration, so that the Slint compiler +generates the button_native.h header file from the Slint file. It contains the generated class `Recipe`. For each property, a getter (`get_counter`) and a setter (`set_counter`) is generated. For the callback, a function to set the callback is generated (`on_button_pressed`) @@ -143,8 +142,8 @@ export Recipe := Window { ``` This example introduces the `Slider` widget. -It also introduces interpolation in string literal: you can use `\{...}` in them -and the code is rendered to a string. +It also introduces interpolation in string literal: Use `\{...}` in strings to render +code between the curly braces to a string. ## Animations @@ -183,11 +182,11 @@ export Recipe := Window { } ``` -We'd usually use Layout or Box to position elements, but in this case we do the -positioning manually using the `x`, `y`, `width`, `height` property. +Layouts are typically used to position elements automatically. In this example they are positioned +manually using the `x`, `y`, `width`, `height` properties. -Notice the `animate x` block that specify an animation that is run when the property -is changed. Either because the property is set in a callback, or if its binding value changes. +Notice the `animate x` block that specifies an animation. It is run when the property +changes: Either because the property is set in a callback, or if its binding value changes. ### Animation Sequence @@ -230,7 +229,7 @@ export Recipe := Window { } ``` -We use `delay` to make one animation run after the other. +This example uses the `delay` property to make one animation run after another. ## States @@ -388,8 +387,7 @@ export Recipe := Window { ### Invoke a globally registered native callback from Slint -It is usefull to use Global Singleton to implement logic or store properties -set by the native code. +This example uses a global singleton to implement common logic in native code. It can also be used to store properties and they can be set by native code. Please note that in the preview only visualize the slint code, but is not connected to the native code.