From 886a31f8402d233e317630a3cefd9e2b6aef0b6c Mon Sep 17 00:00:00 2001 From: Chris Chinchilla Date: Mon, 10 Jun 2024 11:42:51 +1000 Subject: [PATCH 1/2] 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 ++-- .../src/language/concepts/translations.md | 110 ++++++++++++------ docs/reference/src/language/index.rst | 18 +-- 7 files changed, 116 insertions(+), 70 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/concepts/translations.md b/docs/reference/src/language/concepts/translations.md index 9cd394a0947..2cbe33d00b6 100644 --- a/docs/reference/src/language/concepts/translations.md +++ b/docs/reference/src/language/concepts/translations.md @@ -1,21 +1,38 @@ + # Translations -Use Slint's translation infrastructure to make your application available in different languages. +Slint's translation infrastructure makes your application available in different languages. + +## Prerequisites + +Install the `slint-tr-extractor` tool to extract translatable strings from `.slint` files: + +```sh +cargo install slint-tr-extractor +``` + +## Overview Complete the following steps to translate your application: -1. Identify all user visible strings that need to be translated and annotate them with the `@tr()` macro. -2. Extract annotated strings using the `slint-tr-extractor` tool and generate `.pot` files. + + +1. Identify all user visible strings that need translation and annotate them with the `@tr()` macro. +2. Extract annotated strings by running the `slint-tr-extractor` tool and generate `.pot` files. + + + 3. Use a third-party tool to translate the strings into a target language, as `.po` files. -4. Use gettext's `msgfmt` tool to convert `.po` files into run-time loadable `.mo` files. +4. Use [gettext's `msgfmt`](https://www.gnu.org/software/gettext/manual/gettext.html) tool to convert `.po` files into run-time loadable `.mo` files. 5. Use Slint's API to select and load `.mo` files at run-time, based on the user's locale settings. - At this point, all strings marked for translation will automatically be rendered in the target language. + + At this point, all strings marked for translation will automatically be rendered in the target language. ## Annotating Translatable Strings -Use the `@tr` macro in `.slint` files to mark that a string is meant to be translated. This macro -will take care of both the translation and the formatting, by replacing `{}` placeholders. +Use the `@tr` macro in `.slint` files to mark that a string for translation. This macro +takes care of both the translation and the formatting by replacing `{}` placeholders. The first argument must be a plain string literal, followed by the arguments: @@ -34,8 +51,8 @@ The `@tr` macro replaces each `{}` placeholder in the string marked for translat It's also possible to re-order the arguments using `{0}`, `{1}`, and so on. Translators can use ordered placeholders even if the original string did not. -The literal characters `{` and `}` may be included in a string by preceding them with the same character. -For example, the `{` character is escaped with `{{` and the `}` character is escaped with `}}`. +You can include the literal characters `{` and `}` in a string by preceding them with the same character. +For example, escaping the `{` character with `{{` and the `}` character with `}}`. ### Plurals @@ -75,7 +92,6 @@ export component MenuItem { ## Extract Translatable Strings - Use the `slint-tr-extractor` tool to generate a `.pot` file from `.slint` files. You can run it like so: @@ -83,91 +99,103 @@ You can run it like so: find -name \*.slint | xargs slint-tr-extractor -o MY_PROJECT.pot ``` -This will create a file called `MY_PROJECT.pot`. Replace MY_PROJECT with your actual project name. -To learn how the project name affects the lookup of translations, see the sections below. +This creates a file called `MY_PROJECT.pot`. Replace "MY_PROJECT" with your actual project name. +To learn how the project name affects the lookup of translations, read the sections below. + +:::info `.pot` files are [Gettext](https://www.gnu.org/software/gettext/) template files. +::: + ## Translate the Strings Start a new translation by creating a `.po` file from a `.pot` file. Both file formats are identical. You can either copy the file manually or use a tool like Gettext's `msginit` to start a new `.po` file. -The `.po` file will contain the strings in a target language. +The `.po` file contains the strings in a target language. -`.po` and `.pot` files are plain text files, that you can edit with a text editor. We recommend +`.po` and `.pot` files are plain text files that you can edit with a text editor. We recommend using a dedicated translation tool for working with them, such as the following: - - [poedit](https://poedit.net/) - - [OmegaT](https://omegat.org/) - - [Lokalize](https://userbase.kde.org/Lokalize) - - [Transifex](https://www.transifex.com/) (web interface) +- [poedit](https://poedit.net/) +- [OmegaT](https://omegat.org/) +- [Lokalize](https://userbase.kde.org/Lokalize) +- [Transifex](https://www.transifex.com/) (web interface) ## Convert `.po` Files to `.mo` Files -The human readable `.po` files need to be converted into machine-friendly `.mo` files, a binary representation -that is very efficient to read. +Convert the human readable `.po` files into machine-friendly `.mo` files, which are a binary representation +that is more efficient to read by code. Use [Gettext](https://www.gnu.org/software/gettext/)'s `msgfmt` command line tool to convert `.po` files to `.mo` files: -``` +```sh msgfmt translation.po -o translation.mo ``` ## Select and Load `.mo` Files at Run-Time Slint uses the [Gettext](https://www.gnu.org/software/gettext/) library to load translations at run-time. -Gettext locates the translation file in the following location: -Gettext expects translation files - called message catalogs - to be placed in following directory hierarchy: +Gettext expects translation files - called message catalogs - in following directory hierarchy: ``` dir_name/locale/LC_MESSAGES/domain_name.mo ``` -* `dir_name`: the base directory that you can choose freely. -* `locale`: The name of the user's locale for a given target language, such as `fr` for French, or `de` for German. - The locale is typically determined using environment variables that your operating system sets. -* `domain_name`: Selected based on the programming language you're using Slint with. +- `dir_name`: the base directory that you can choose freely. +- `locale`: The name of the user's locale for a given target language, such as `fr` for French, or `de` for German. + + The locale is typically determined using environment variables that your operating system sets. + +- `domain_name`: Selected based on the programming language you're using Slint with. -For more info, see the [Gettext documentation](https://www.gnu.org/software/gettext/manual/gettext.html#Locating-Catalogs). +:::info + +Read the [Gettext documentation](https://www.gnu.org/software/gettext/manual/gettext.html#Locating-Catalogs) for more information. + +::: ### Select and Load Translations with Rust -First, enable the `gettext` feature of the `slint` create to gain access to the translations API + + +First, enable the `gettext` feature of the `slint` crate to gain access to the translations API and activate run-time translation support. -Next, use the `slint::init_translations!` to specify the base location of your `.mo` files. This is -the `dir_name` in the scheme of the previous section. The `.mo` files are expected to be in the +Next, use the `slint::init_translations!` macro to specify the base location of your `.mo` files. This is +the `dir_name` in the scheme of the previous section. Slint expects the `.mo` files to be in the corresponding sub-directories and their file name - `domain_name` - must match the package name in your `Cargo.toml`. This is often the same as the crate name. - For example: ```rust slint::init_translations!(concat!(env!("CARGO_MANIFEST_DIR"), "/lang/")); ``` -Suppose your `Cargo.toml` contains the following lines and the user's locale is `fr`: +For example, if your `Cargo.toml` contains the following lines and the user's locale is `fr`: ```toml [package] name = "gallery" ``` -With these settings, Slint will look for `gallery.mo` in the `lang/fr/LC_MESSAGES/gallery.mo`. +With these settings, Slint looks for `gallery.mo` in the `lang/fr/LC_MESSAGES/gallery.mo`. ### Select and Load Translations with C++ -First, enable the `SLINT_FEATURE_GETTEXT` cmake option when compiling Slint, to gain access to + + +First, enable the `SLINT_FEATURE_GETTEXT` cmake option when compiling Slint to gain access to the translations API and activate run-time translation support. In C++ applications using cmake, the `domain_name` is the CMake target name. Next, bind the text domain to a path using the standard gettext library. -To do so, add this in your CMakeLists.txt +To do so, add this in your `CMakeLists.txt` file: ```cmake find_package(Intl) @@ -195,13 +223,19 @@ int main() } ``` -Suppose you're using the above and the user's locale is set to `fr`, -Slint will look for `my_application.mo` in the `lang/fr/LC_MESSAGES/` directory. +For example, if you're using the above and the user's locale is `fr`, +Slint looks for `my_application.mo` in the `lang/fr/LC_MESSAGES/` directory. ## Previewing Translations with `slint-viewer` + + Use `slint-viewer` to preview translations when previewing `.slint` files: +```rust +cargo install slint-viewer +``` + 1. Enable the `gettext` feature when compiling `slint-viewer`. 2. Use the `--translation-domain` and `translation-dir` command line options to load translations and display them based on the current locale. 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. From 6ad8213633725705783ea04c78b2d33784f6049a Mon Sep 17 00:00:00 2001 From: Chris Chinchilla Date: Wed, 10 Jul 2024 13:47:39 +0200 Subject: [PATCH 2/2] Feedback --- .../src/language/concepts/translations.md | 24 ++++++++----------- docs/reference/src/language/index.rst | 7 ------ 2 files changed, 10 insertions(+), 21 deletions(-) diff --git a/docs/reference/src/language/concepts/translations.md b/docs/reference/src/language/concepts/translations.md index 2cbe33d00b6..2871121c455 100644 --- a/docs/reference/src/language/concepts/translations.md +++ b/docs/reference/src/language/concepts/translations.md @@ -4,7 +4,9 @@ Slint's translation infrastructure makes your application available in different languages. -## Prerequisites +## Overview + +:::tip Prerequisite Install the `slint-tr-extractor` tool to extract translatable strings from `.slint` files: @@ -12,22 +14,18 @@ Install the `slint-tr-extractor` tool to extract translatable strings from `.sli cargo install slint-tr-extractor ``` -## Overview +::: Complete the following steps to translate your application: - 1. Identify all user visible strings that need translation and annotate them with the `@tr()` macro. 2. Extract annotated strings by running the `slint-tr-extractor` tool and generate `.pot` files. - - - 3. Use a third-party tool to translate the strings into a target language, as `.po` files. 4. Use [gettext's `msgfmt`](https://www.gnu.org/software/gettext/manual/gettext.html) tool to convert `.po` files into run-time loadable `.mo` files. 5. Use Slint's API to select and load `.mo` files at run-time, based on the user's locale settings. - At this point, all strings marked for translation will automatically be rendered in the target language. +At this point, all strings marked for translation are automatically rendered in the target language. ## Annotating Translatable Strings @@ -159,9 +157,7 @@ Read the [Gettext documentation](https://www.gnu.org/software/gettext/manual/get ### Select and Load Translations with Rust - - -First, enable the `gettext` feature of the `slint` crate to gain access to the translations API +First, enable the `gettext` feature of the `slint` crate in the `features` section to gain access to the translations API and activate run-time translation support. Next, use the `slint::init_translations!` macro to specify the base location of your `.mo` files. This is @@ -186,8 +182,6 @@ With these settings, Slint looks for `gallery.mo` in the `lang/fr/LC_MESSAGES/ga ### Select and Load Translations with C++ - - First, enable the `SLINT_FEATURE_GETTEXT` cmake option when compiling Slint to gain access to the translations API and activate run-time translation support. @@ -228,14 +222,16 @@ Slint looks for `my_application.mo` in the `lang/fr/LC_MESSAGES/` directory. ## Previewing Translations with `slint-viewer` - +:::tip Prerequisite Use `slint-viewer` to preview translations when previewing `.slint` files: -```rust +```sh cargo install slint-viewer ``` +::: + 1. Enable the `gettext` feature when compiling `slint-viewer`. 2. Use the `--translation-domain` and `translation-dir` command line options to load translations and display them based on the current locale. diff --git a/docs/reference/src/language/index.rst b/docs/reference/src/language/index.rst index bc298322199..c14d734cb7c 100644 --- a/docs/reference/src/language/index.rst +++ b/docs/reference/src/language/index.rst @@ -1,15 +1,12 @@ .. Copyright © SixtyFPS GmbH .. SPDX-License-Identifier: MIT -.. A lot of repitition - Introduction ============ 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. @@ -40,7 +37,3 @@ 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. -.. 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.