From 6e21fe8ee301fe7fe11d2e7726e515196c1dec5b Mon Sep 17 00:00:00 2001 From: Chris Chinchilla Date: Mon, 10 Jun 2024 11:42:51 +1000 Subject: [PATCH] Draft --- .../src/language/concepts/container.md | 9 ++++--- docs/reference/src/language/concepts/file.md | 12 ++++++--- docs/reference/src/language/concepts/focus.md | 9 ++++--- docs/reference/src/language/concepts/fonts.md | 3 ++- .../src/language/concepts/layouting.md | 25 ++++++++++--------- docs/reference/src/language/index.rst | 18 +++++++------ 6 files changed, 44 insertions(+), 32 deletions(-) diff --git a/docs/reference/src/language/concepts/container.md b/docs/reference/src/language/concepts/container.md index ed11a7e4445..a88c0700063 100644 --- a/docs/reference/src/language/concepts/container.md +++ b/docs/reference/src/language/concepts/container.md @@ -1,9 +1,10 @@ + # Container Components When creating components, it's sometimes useful to influence where child -elements are placed when used. For example, imagine a component that draws -a label above whatever element the user places inside: +elements are placed when used. For example, a component that draws +a label above an element inside: ```slint,ignore export component MyApp inherits Window { @@ -19,8 +20,8 @@ export component MyApp inherits Window { ``` You can implement such a `BoxWithLabel` using a layout. By default child elements like -the `Text` element become direct children of the `BoxWithLabel`, but we need them to become -children of our layout instead. For this purpose, you can change the default child placement by using +the `Text` element become direct children of the `BoxWithLabel`, but for this example they need to become +children of the layout instead. To do this can change the default child placement by using the `@children` expression inside the element hierarchy of a component: ```slint diff --git a/docs/reference/src/language/concepts/file.md b/docs/reference/src/language/concepts/file.md index 07c5e575034..f4ad752c99d 100644 --- a/docs/reference/src/language/concepts/file.md +++ b/docs/reference/src/language/concepts/file.md @@ -1,7 +1,8 @@ + # The `.slint` File -User interfaces are written in the Slint language and saved in files with the `.slint` extension. +You write user interfaces in the Slint language and saved in files with the `.slint` extension. Each `.slint` file defines one or several components. These components declare a tree of elements. Components form the basis of composition in Slint. Use them @@ -35,15 +36,14 @@ export component MyApp inherits Window { text: "world"; } } - ``` Both `MyButton` and `MyApp` are components. `Window` and `Rectangle` are built-in elements used by `MyApp`. `MyApp` also re-uses the `MyButton` component as two separate elements. -Elements have properties, which you can assign values to. Here we assign a string +Elements have properties, which you can assign values to. The example above assigns a string constant "hello" to the first `MyButton`'s `text` property. You -can also assign entire expressions. Slint will re-evaluate the expressions when any +can also assign entire expressions. Slint re-evaluates the expressions when any of the properties they depend on change, which makes the user-interface reactive. You can name elements using the `:=` syntax: @@ -69,8 +69,12 @@ export component MyApp inherits Window { } ``` +:::note + Names have to be valid [identifiers](../syntax/identifiers.md). +::: + Some elements are also accessible under pre-defined names: - `root` refers to the outermost element of a component. diff --git a/docs/reference/src/language/concepts/focus.md b/docs/reference/src/language/concepts/focus.md index 2c2d497c3a5..0bd352af82e 100644 --- a/docs/reference/src/language/concepts/focus.md +++ b/docs/reference/src/language/concepts/focus.md @@ -1,10 +1,11 @@ + # Focus Handling -Certain elements such as `TextInput` accept not only input from the mouse/finger but +Certain elements such as `TextInput` accept input from the mouse/finger and also key events originating from (virtual) keyboards. In order for an item to receive -these events, it must have the focus. This is visible through the `has-focus` (out) property. - +these events, it must have focus. This is visible through the `has-focus` (out) property. + You can manually activate the focus on an element by calling `focus()`: ```slint @@ -43,7 +44,7 @@ export component App inherits Window { } ``` -After the focus is cleared, keyboard input to the window is discarded, until another element is explicitly +After clearing the focus, keyboard input to the window is discarded until another element is explicitly focused. For example by calling `focus()`, an element acquiring focus when the user clicks on it, or when pressing tab and the first focusable element is found. diff --git a/docs/reference/src/language/concepts/fonts.md b/docs/reference/src/language/concepts/fonts.md index 1762f80e8c2..25e5a9e6010 100644 --- a/docs/reference/src/language/concepts/fonts.md +++ b/docs/reference/src/language/concepts/fonts.md @@ -1,4 +1,5 @@ + # Font Handling Elements such as `Text` and `TextInput` can render text and allow customizing the appearance of the text through @@ -6,7 +7,7 @@ different properties. The properties prefixed with `font-`, such as `font-family affect the choice of font used for rendering to the screen. If any of these properties isn't specified, the `default-font-` values in the surrounding `Window` element apply, such as `default-font-family`. -The fonts chosen for rendering are automatically picked up from the system. It's also possible to include custom +The fonts chosen for rendering are automatically picked up from the system running the application. It's also possible to include custom fonts in your design. A custom font must be a TrueType font (`.ttf`), a TrueType font collection (`.ttc`) or an OpenType font (`.otf`). You can select a custom font with the `import` statement: `import "./my_custom_font.ttf"` in a .slint file. This instructions the Slint compiler to include the font and makes the font families globally available for use with diff --git a/docs/reference/src/language/concepts/layouting.md b/docs/reference/src/language/concepts/layouting.md index 2482e60e287..bcf487354f0 100644 --- a/docs/reference/src/language/concepts/layouting.md +++ b/docs/reference/src/language/concepts/layouting.md @@ -1,4 +1,5 @@ + # Positioning and Layout of Elements All visual elements are shown in a window. The `x` and `y` properties store @@ -64,11 +65,11 @@ configured with. For example, on a modern High-DPI display the device pixel rati so every logical pixel occupies 2 physical pixels. On an older screen the user interface scales without any adaptations. -Additionally, the `width` and `height` properties can also be specified as a `%` percentage +You can also specify the `width` and `height` properties as a `%` percentage unit, which applies relative to the parent element. For example a `width: 50%` means half of the parent's `width`. -The default values for `x` and `y` properties are such that elements are centered within their +The default values for `x` and `y` properties center elements within their parent. The default values for `width` and `height` depend on the type of element. Some elements are sized @@ -81,19 +82,19 @@ don't have content and default to fill their parent element when they do not hav - `Flickable` Layouts are also defaulting to fill the parent, regardless of their own preferred size. - + Other elements (including custom ones without base) default to using their preferred size. ### Preferred size -The preferred size of elements can be specified with the `preferred-width` and `preferred-height` properties. +You can specify the preferred size of elements with the `preferred-width` and `preferred-height` properties. When not explicitly set, the preferred size depends on the children, and is the preferred size of the child that has the bigger preferred size, whose `x` and `y` property are not set. The preferred size is therefore computed from the child to the parent, just like other constraints (maximum and minimum size), unless explicitly overwritten. A special case is to set the preferred size to be the size of the parent using `100%` as value. -For example,this component will use the size of the parent by default: +For example, this component uses the size of the parent by default: ```slint export component MyComponent { @@ -146,7 +147,7 @@ All layout elements have the following properties in common: - `padding`: This specifies the padding within the layout, the space between the elements and the border of the layout. -For more fine grained control, the `padding` property can be split into properties for each side of the layout: +For more fine grained control, you can split the `padding` property into properties for each side of the layout: - `padding-left` - `padding-right` @@ -174,7 +175,7 @@ export component Example inherits Window { } ``` -The example below, on the other hand, specifies that the rectangles shall align +The example below, on the other hand, specifies that the rectangles align to the start of the layout (the visual left). That results in no stretching but instead the rectangles retain their specified minimum width: @@ -234,7 +235,7 @@ the minimum size of an inner layout, whatever is bigger. The elements are placed according to the alignment. The size of elements is bigger than the minimum size only if the `alignment` property of the layout is `LayoutAlignment.stretch` (the default) -This example show the different alignment possibilities +This example show the different alignment possibilities: ```slint export component Example inherits Window { @@ -294,7 +295,7 @@ then the extra space is shared amongst element proportional to their stretch fac `horizontal-stretch` and `vertical-stretch` properties. The stretched size won't exceed the maximum size. The stretch factor is a floating point number. The elements that have a default content size usually defaults to 0 while elements that default to the size of their parents defaults to 1. -An element of a stretch factor of 0 will keep its minimum size, unless all the other elements also have a stretch +An element of a stretch factor of 0 keep its minimum size, unless all the other elements also have a stretch factor of 0 or reached their maximum size. Examples: @@ -333,7 +334,7 @@ export component Example inherits Window { ### `for` -The VerticalLayout and Horizontal layout may also contain `for` or `if` expressions: +The VerticalLayout and HorizontalLayout can also contain `for` or `if` expressions: ```slint export component Example inherits Window { @@ -353,7 +354,7 @@ export component Example inherits Window { The GridLayout lays the element in a grid. Each element gains the properties `row`, `col`, `rowspan`, and `colspan`. -One can either use a `Row` sub-element, or set the `row` property explicitly. +You can either use a `Row` sub-element, or set the `row` property explicitly. These properties must be statically known at compile time, so it's impossible to use arithmetic or depend on properties. As of now, the use of `for` or `if` isn't allowed in a grid layout. @@ -378,7 +379,7 @@ export component Foo inherits Window { } ``` -This example use the `col` and `row` property +This example use the `col` and `row` property: ```slint export component Foo inherits Window { diff --git a/docs/reference/src/language/index.rst b/docs/reference/src/language/index.rst index bb02f4c6b7a..bc298322199 100644 --- a/docs/reference/src/language/index.rst +++ b/docs/reference/src/language/index.rst @@ -1,29 +1,31 @@ .. Copyright © SixtyFPS GmbH .. SPDX-License-Identifier: MIT +.. A lot of repitition + Introduction ============ -`Slint `_ comes with an easy to learn and use language for you to describe user -interfaces with. It is readable to both humans and machines. +Slint is an easy to learn and use language to describe user +interfaces. It is readable to both humans and machines. +.. ??? This way, we have excellent tooling on one side, while also enabling designers and developers to know exactly what happens, by reading the code their machine uses to display the user interfaces. -This Slint language is either interpreted at run-time or compiled to native -code, which gets built into your application together with the code in the same +This Slint code is either interpreted at run-time or compiled to native +code, which gets built into your application together with the code in the programming language providing the business logic. The Slint compiler can optimize the user interface and any resources it uses at compile time, so that user interfaces written in Slint use few resources, with regards to performance and storage. The Slint language enforces a separation of user interface from business logic, -using interfaces you can define for your project. This enables a fearless +using interfaces you can define for your project. This enables cooperation between design-focused team members and those concentrating on the programming side of the project. - The Slint language describes extensible graphical user interfaces using the `Slint framework `_ @@ -38,5 +40,7 @@ The Slint language describes extensible graphical user interfaces using the - Build highly customized user interfaces with the :ref:`builtin elements ` and pre-built :ref:`widgets ` provided. -It only describes the user interface and it is not a programming language. The business +.. Again, repitition + +Slint only describes the user interface and is not a programming language. The business logic is written in a different programming language using the Slint API.