language-servers/slint
1
0
Fork 0
mirror of https://github.com/slint-ui/slint.git synced 2025-08-03 18:29:09 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

Use sphinx to generate the Slint language reference (#2218)

Browse source 
* docs: Move the langref to sphinx

* docs: Use sphinx to build nighly doc snapshot of langref
This commit is contained in:
Tobias Hunger 2023-02-10 11:51:36 +01:00 • committed by GitHub
parent fb8a7fb1e5
commit e1e4be2497
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
43 changed files with 1082 additions and 812 deletions
Download patch file Download diff file Expand all files Collapse all files

7
.github/workflows/build_docs.yaml vendored
View file

@ -84,8 +84,7 @@ jobs:
run: mdbook build
working-directory: docs/tutorial/cpp
- name: "Slint Language Reference"
run: mdbook build
working-directory: docs/langref
run: cargo xtask slintdocs --show-warnings
- name: "Node docs"
run: |
npm install --ignore-scripts
@ -98,13 +97,13 @@ jobs:
path: |
target/doc
target/cppdocs/html
target/slintdocs/html
api/node/docs
docs/site
docs/langref/book/html
docs/tutorial/rust/book/html
docs/tutorial/cpp/book/html
- name: "Check for docs warnings in internal crates"
run: cargo +nightly doc --workspace --no-deps --all-features --exclude slint-node --exclude mcu-board-support --exclude printerdemo_mcu --exclude carousel --exclude test-* --exclude plotter
- name: Clean cache # Don't cache docs to avoid them including removed classes being published
run: |
rm -rf target/doc target/cppdocs api/node/docs docs/tutorial/rust/book docs/tutorial/cpp/book
rm -rf target/doc target/cppdocs target/slintdocs api/node/docs docs/tutorial/rust/book docs/tutorial/cpp/book

3
.github/workflows/nightly_snapshot.yaml vendored
View file

@ -308,7 +308,8 @@ jobs:
mkdir -p snapshots/$target_branch/docs/node
cp -a ../api/node/docs/* snapshots/$target_branch/docs/node/
mkdir -p snapshots/$target_branch/docs/slint
cp -a ../docs/langref/book/html/* snapshots/$target_branch/docs/slint/
cp -a ../target/slintdocs/html/* snapshots/$target_branch/docs/slint/
git add snapshots/$target_branch/docs
git add -u snapshots/$target_branch/docs

6
docs/langref/.gitignore vendored
View file

@ -1 +1,5 @@
book
# Copyright © 2021 SixtyFPS GmbH <info@slint-ui.com>
# SPDX-License-Identifier: GPL-3.0-only OR LicenseRef-Slint-commercial
Pipfile.lock
build

18
docs/langref/Pipfile Normal file
View file

@ -0,0 +1,18 @@
# Copyright © 2021 SixtyFPS GmbH <info@slint-ui.com>
# SPDX-License-Identifier: GPL-3.0-only OR LicenseRef-Slint-commercial
[[source]]
name = "pypi"
url = "https://pypi.org/simple"
verify_ssl = true
[dev-packages]
[packages]
sphinx-rtd-theme = "1.0.0"
sphinx = "4.5.0"
myst_parser = "0.17.2"
sphinx-markdown-tables = "0.0.15"
[requires]
python_version = "3"

15
docs/langref/_static/theme_tweak.css Normal file
View file

@ -0,0 +1,15 @@
.wy-table-responsive table td,
.wy-table-responsive table th {
white-space: normal;
}
.wy-table-responsive {
margin-bottom: 24px;
max-width: 100%;
overflow: visible;
}
img.logo {
max-height: 70px;
border-radius: 12% !important;
}

4
docs/langref/_templates/layout.html Normal file
View file

@ -0,0 +1,4 @@
{% extends "!layout.html" %} {% block scripts %} {{ super() }} {% include
"../../resources/slint-docs-preview.html" %}
<!-- {% include "../../resources/slint-docs-highlight.html" %} -- Too many GL contexts! -->
{% endblock %}

12
docs/langref/book.toml
View file

@ -1,12 +0,0 @@
[book]
authors = ["Slint Developers <info@slint-ui.com>"]
language = "en"
multilingual = false
src = "src"
title = "Slint Language Reference"
[output.html]
theme = "../tutorial/theme"
[output.linkcheck] # enable the "mdbook-linkcheck" renderer
optional = true

83
docs/langref/conf.py Normal file
View file

@ -0,0 +1,83 @@
# Copyright © 2021 SixtyFPS GmbH <info@slint-ui.com>
# SPDX-License-Identifier: GPL-3.0-only OR LicenseRef-Slint-commercial
# Configuration file for the Sphinx documentation builder.
#
# This file only contains a selection of the most common options. For a full
# list see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html
# -- Path setup --------------------------------------------------------------
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))
import textwrap
# -- Project information -----------------------------------------------------
project = "Slint Book"
copyright = "2023, info@slint-ui.com"
author = "Slint Developers <info@slint-ui.com>"
# The full version, including alpha/beta/rc tags
version = "1.0.0"
# -- General configuration ---------------------------------------------------
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = ["myst_parser", "sphinx_markdown_tables"]
# Add any paths that contain templates here, relative to this directory.
templates_path = ["_templates"]
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = [
"_build",
"html/_static/collapsible-lists/LICENSE.md",
"Thumbs.db",
".DS_Store",
"README.md",
]
# -- Options for HTML output -------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = "sphinx_rtd_theme"
html_theme_options = {"collapse_navigation": False}
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ["_static"]
html_show_sourcelink = False
html_logo = "https://slint-ui.com/logo/slint-logo-small-light.svg"
myst_enable_extensions = [
"html_image",
]
# Annotate h1/h2 elements with anchors
myst_heading_anchors = 4
rst_epilog = """
"""
def setup(app):
app.add_css_file("theme_tweak.css")

6
docs/langref/genindex.rst Normal file
View file

@ -0,0 +1,6 @@
.. Copyright © SixtyFPS GmbH <info@slint-ui.com>
.. SPDX-License-Identifier: GPL-3.0-only OR LicenseRef-Slint-commercial
===========
Index (C++)
===========

69
docs/langref/index.rst Normal file
View file

@ -0,0 +1,69 @@
.. Copyright © SixtyFPS GmbH <info@slint-ui.com>
.. SPDX-License-Identifier: GPL-3.0-only OR LicenseRef-Slint-commercial
Welcome to the Slint Language Reference
========================================
Introduction
------------
The Slint design markup language describes extensible graphical user interfaces.
- Place and compose a tree of visual elements in a window using a textual representation.
- Configure the appearance of elements via properties. For example a `Text` element has a `text`
property, while a `Rectangle` element has a `background` color.
- Assign binding expressions to properties to automatically compute values that depend on other properties.
- Group binding expressions together with named states and conditions.
- Declare animations on properties and states to make the user interface feel alive.
- Build your own re-usable components and share them in `.slint` module files.
- Define data structures and models and access them from programming languages.
- Build highly customized user interfaces with the [builtin elements](builtin_elements.md)
and pre-built [widgets](widgets.md) provided.
Architecture
------------
An application is composed of the business logic written in C++ and the `.slint` user interface design markup, which
is compiled to native code.
.. toctree::
:maxdepth: 2
:caption: Slint Language Concepts
src/concepts.md
src/purity.md
src/layouting.md
src/focus.md
src/fonts.md
.. toctree::
:maxdepth: 2
:caption: Slint Language Reference
src/comments.md
src/identifiers.md
src/types.md
src/properties.md
src/expressions.md
src/functions.md
src/callbacks.md
src/statements.md
src/repetitions.md
src/conditions.md
src/animations.md
src/states.md
src/globals.md
src/modules.md
src/legacy_syntax.md
.. toctree::
:maxdepth: 4
:caption: Slint Language Builtins
src/builtin_callbacks.md
src/builtin_elements.md
src/builtin_enums.md
src/builtin_functions.md
src/builtin_namespaces.md
src/builtin_structs.md
src/widgets.md

52
docs/langref/src/SUMMARY.md
View file

@ -1,52 +0,0 @@
# Summary
- [Introduction](intro.md)
- [`.slint` Files](file_format.md)
- [Container Elements](containers.md)
- [Comments](comments.md)
- [Identifiers](identifiers.md)
- [Properties](properties.md)
- [Bindings](bindings.md)
- [Two-way Bindings](aliases.md)
- [Types](types.md)
- [Strings](strings.md)
- [Colors and Brushes](brushes.md)
- [Methods of Brushes and Colors](brushes_methods.md)
- [Linear Gradients](lin_gradients.md)
- [Radial Gradients](rad_gradients.md)
- [Images](images.md)
- [Structs](structs.md)
- [Arrays and Models](models.md)
- [Relative Length](rel-length.md)
- [Conversions](conversions.md)
- [Functions](functions.md)
- [Callback](callback.md)
- [Callback Aliases](callback_alias.md)
- [Purity](purity.md)
- [Expressions](expressions.md)
- [Statements](statements.md)
- [Repetition](repetition.md)
- [Conditional Element](condition.md)
- [Animations](animations.md)
- [States](states.md)
- [Transitions](tranitions.md)
- [Global Singletons](globals.md)
- [Modules](modules.md)
- [Module Syntax](module_syntax.md)
- [Focus Handling](focus.md)
- [Font Handling](fonts.md)
- [Legacy Syntax](legacy_syntax.md)
# Builtins
- [Functions](builtin_functions.md)
- [Callbacks](builtin_callbacks.md)
- [`Math` Namespace](math.md)
- [`Colors` Namespace](colors.md)
- [Elements](builtin_elements.md)
- [Enums](builtin_enums.md)
- [Widgets](widgets.md)
# Positioning and Layouting
- [Positioning and Layout of Elements](layouting.md)

20
docs/langref/src/aliases.md
View file

@ -1,20 +0,0 @@
## Two-way Bindings
Create two-way bindings between properties with the `<=>` syntax. These properties will be linked
together and always contain the same value.
The right hand side of the `<=>` must be a reference to a property of the same type.
The property type is optional with two-way bindings, it will be inferred if not specified.
```slint,no-preview
export component Example {
in property<brush> rect-color <=> r.background;
// it is allowed to omit the type to have it automatically inferred
in property rect-color2 <=> r.background;
r:= Rectangle {
width: parent.width;
height: parent.height;
background: blue;
}
}
```

28
docs/langref/src/bindings.md
View file

@ -1,28 +0,0 @@
## Bindings
The binding expression is automatically re-evaluated when properties accessed in the expression change.
In the following example, the text of the button automatically changes when
the user presses the button. Incrementing the `counter` property automatically
invalidates the expression bound to `text` and triggers a re-evaluation.
```slint
import { Button } from "std-widgets.slint";
export component Example inherits Window {
preferred-width: 50px;
preferred-height: 50px;
Button {
property <int> counter: 3;
clicked => { self.counter += 3 }
text: self.counter * 2;
}
}
```
The re-evaluation happens lazily when the property is queried.
Internally, a dependency is registered for any property accessed while evaluating a binding.
When a property changes, the dependencies are notified and all dependent bindings
are marked as dirty.
Callbacks in native code by default don't depend on any properties unless they query a property in the native code.

70
docs/langref/src/brushes.md
View file

@ -1,4 +1,4 @@
## Colors and Brushes
# Colors and Brushes
Color literals follow the syntax of CSS:
@ -16,3 +16,71 @@ draw the outline.
CSS Color names are only in scope in expressions of type `color` or `brush`. Otherwise, you can access
colors from the `Colors` namespace.
## Methods
All colors and brushes define the following methods:
- **`brighter(factor: float) -> Brush`**
Returns a new color derived from this color but has its brightness increased by the specified factor.
For example if the factor is 0.5 (or for example 50%) the returned color is 50% brighter. Negative factors
decrease the brightness.
- **`darker(factor: float) -> Brush`**
Returns a new color derived from this color but has its brightness decreased by the specified factor.
For example if the factor is .5 (or for example 50%) the returned color is 50% darker. Negative factors
increase the brightness.
## Linear Gradients
Linear gradients describe smooth, colorful surfaces. They're specified using an angle and a series of
color stops. The colors will be linearly interpolated between the stops, aligned to an imaginary line
that is rotated by the specified angle. This is called a linear gradient and is specified using the
`@linear-gradient` macro with the following signature:
**`@linear-gradient(angle, color percentage, color percentage, ...)`**
The first parameter to the macro is an angle (see [Types](#types)). The gradient line's starting point
will be rotated by the specified value.
Following the initial angle is one or multiple color stops, describe as a space separated pair of a
`color` value and a `percentage`. The color specifies which value the linear color interpolation should
reach at the specified percentage along the axis of the gradient.
The following example shows a rectangle that's filled with a linear gradient that starts with a light blue
color, interpolates to a very light shade in the center and finishes with an orange tone:
```slint
export component Example inherits Window {
preferred-width: 100px;
preferred-height: 100px;
Rectangle {
background: @linear-gradient(90deg, #3f87a6 0%, #ebf8e1 50%, #f69d3c 100%);
}
}
```
## Radial Gradients
Linear gradiants are like real gradiant but the colors is interpolated in a circle instead of
along a line. To describe a readial gradiant, use the `@radial-gradient` macro with the following signature:
**`@radial-gradient(circle, color percentage, color percentage, ...)`**
The first parameter to the macro is always `circle` because only circular radients are supported.
The syntax is otherwise based on the CSS `radial-gradient` function.
Example:
```slint
export component Example inherits Window {
preferred-width: 100px;
preferred-height: 100px;
Rectangle {
background: @radial-gradient(circle, #f00 0%, #0f0 50%, #00f 100%);
}
}
```

15
docs/langref/src/brushes_methods.md
View file

@ -1,15 +0,0 @@
### Methods
All colors and brushes define the following methods:
- **`brighter(factor: float) -> Brush`**
Returns a new color derived from this color but has its brightness increased by the specified factor.
For example if the factor is 0.5 (or for example 50%) the returned color is 50% brighter. Negative factors
decrease the brightness.
- **`darker(factor: float) -> Brush`**
Returns a new color derived from this color but has its brightness decreased by the specified factor.
For example if the factor is .5 (or for example 50%) the returned color is 50% darker. Negative factors
increase the brightness.

6
docs/langref/src/builtin_callbacks.md
View file

@ -1,4 +1,6 @@
# Builtin callbacks
# Builtin Callbacks
## `init()`
Every element implicitly declares an `init` callback. You can assign a code block to it that will be invoked when the
element is instantiated and after all properties are initialized with the value of their final binding. The order of
@ -27,7 +29,7 @@ export component MyWindow inherits Window {
}
```
Do not use this callback to initialize properties, because this violates the the declarative principle.
Do not use this callback to initialize properties, because this violates the declarative principle.
Avoid using this callback, unless you need it, for example, in order to notify some native code:
```slint,no-preview

482
docs/langref/src/builtin_elements.md
View file

@ -4,56 +4,56 @@
These properties are valid on all visible items
* **`x`** and **`y`** (*length*): the position of the element relative to its parent
* **`z`** (*float*): Allows to specify a different order to stack the items with its siblings. (default: 0)
* **`width`** and **`height`** (*length*): The size of the element. When set, this overrides the default size.
* **`max-width`** and **`max-height`** (*length*): The maximum size of an element when used in a layout.
* **`min-width`** and **`min-height`** (*length*): The minimum size of an element when used in a layout.
* **`preferred-width`** and **`preferred-height`** (*length*): The preferred size of an element when used in a layout.
* **`col`**, **`row`**, **`colspan`**, **`rowspan`** (*int*): See [`GridLayout`](#gridlayout).
* **`horizontal-stretch`** and **`vertical-stretch`** (*float*): Specify how much relative space these elements are stretching in a layout.
When 0, this means that the elements will not be stretched unless all elements are 0. Builtin widgets have a value of either 0 or 1
* **`opacity`** (*float*): A value between 0 and 1 (or a percentage) that is used to draw the element and its
children with transparency. 0 is fully transparent (invisible), and 1 is fully opaque. (default: 1)
* **`visible`** (*bool*): When set to `false`, the element and all his children will not be drawn
and not react to mouse input (default: `true`)
* **`cache-rendering-hint`** (*bool*): When set to `true`, this provides a hint
to the renderer to cache the contents of the element and all the children into an intermediate
cached layer. For complex sub-trees that rarely change this may speed up the rendering, at the
expense of increased memory consumption. Not all rendering backends support this, so this is
merely a hint. (default: `false`)
* **`dialog-button-role`** (*enum DialogButtonRole*): Specify that this is a button in a `Dialog`.
- **`x`** and **`y`** (_length_): the position of the element relative to its parent
- **`z`** (_float_): Allows to specify a different order to stack the items with its siblings. (default: 0)
- **`width`** and **`height`** (_length_): The size of the element. When set, this overrides the default size.
- **`max-width`** and **`max-height`** (_length_): The maximum size of an element when used in a layout.
- **`min-width`** and **`min-height`** (_length_): The minimum size of an element when used in a layout.
- **`preferred-width`** and **`preferred-height`** (_length_): The preferred size of an element when used in a layout.
- **`col`**, **`row`**, **`colspan`**, **`rowspan`** (_int_): See [`GridLayout`](#gridlayout).
- **`horizontal-stretch`** and **`vertical-stretch`** (_float_): Specify how much relative space these elements are stretching in a layout.
When 0, this means that the elements will not be stretched unless all elements are 0. Builtin widgets have a value of either 0 or 1
- **`opacity`** (_float_): A value between 0 and 1 (or a percentage) that is used to draw the element and its
children with transparency. 0 is fully transparent (invisible), and 1 is fully opaque. (default: 1)
- **`visible`** (_bool_): When set to `false`, the element and all his children will not be drawn
and not react to mouse input (default: `true`)
- **`cache-rendering-hint`** (_bool_): When set to `true`, this provides a hint
to the renderer to cache the contents of the element and all the children into an intermediate
cached layer. For complex sub-trees that rarely change this may speed up the rendering, at the
expense of increased memory consumption. Not all rendering backends support this, so this is
merely a hint. (default: `false`)
- **`dialog-button-role`** (_enum DialogButtonRole_): Specify that this is a button in a `Dialog`.
### Accessibility
Use the following `accessible-` properties to make your items interact well with software like screen readers, braille terminals and other software to make your application accessible.
* **`accessible-role`** (*enum [`AccessibleRole`](builtin_enums.md#accessiblerole)*): The accessibility role of the element. This property is
mandatory to be able to use any other accessible properties. It should be set to a constant value.
The default value is `none` for most elements, but is `text` for the Text element.
* **`accessible-label`** (*string*): The label for an interactive element.
The default value is empty for most elements, or is the value of the `text` property for Text
elements.
* **`accessible-description`** (*string*): The description for the current element.
* **`accessible-checkable`** (*bool*): Whether the element is can be checked or not.
* **`accessible-checked`** (*bool*): Whether the element is checked or not. This maps to the "checked" state of checkboxes, radio buttons, and other widgets.
* **`accessible-has-focus`** (*bool*): Set to true when the current element currently has the focus.
* **`accessible-value`** (*string*): The current value of the item.
* **`accessible-value-maximum`** (*float*): The maximum value of the item. This is used for example by spin boxes.
* **`accessible-value-minimum`** (*float*): The minimum value of the item.
* **`accessible-value-step`** (*float*) The smallest increment or decrement by which the current value can change. This corresponds to the step by which a handle on a slider can be dragged.
- **`accessible-role`** (_enum [`AccessibleRole`](builtin_enums.md#accessiblerole)_): The accessibility role of the element. This property is
mandatory to be able to use any other accessible properties. It should be set to a constant value.
The default value is `none` for most elements, but is `text` for the Text element.
- **`accessible-label`** (_string_): The label for an interactive element.
The default value is empty for most elements, or is the value of the `text` property for Text
elements.
- **`accessible-description`** (_string_): The description for the current element.
- **`accessible-checkable`** (_bool_): Whether the element is can be checked or not.
- **`accessible-checked`** (_bool_): Whether the element is checked or not. This maps to the "checked" state of checkboxes, radio buttons, and other widgets.
- **`accessible-has-focus`** (_bool_): Set to true when the current element currently has the focus.
- **`accessible-value`** (_string_): The current value of the item.
- **`accessible-value-maximum`** (_float_): The maximum value of the item. This is used for example by spin boxes.
- **`accessible-value-minimum`** (_float_): The minimum value of the item.
- **`accessible-value-step`** (_float_) The smallest increment or decrement by which the current value can change. This corresponds to the step by which a handle on a slider can be dragged.
### Drop Shadows
To achieve the graphical effect of a visually elevated shape that shows a shadow effect underneath the frame of
an element, it is possible to set the following `drop-shadow` properties:
* **`drop-shadow-offset-x`** and **`drop-shadow-offset-y`** (*length*): The horizontal and vertical distance
of the shadow from the element's frame. A negative value places the shadow left / above of the element.
* **`drop-shadow-color`** (*color*): The base color of the shadow to use. Typically that color is the starting color
of a gradient that fades into transparency.
* **`drop-shadow-blur`** (*length*): The radius of the shadow that also describes the level of blur applied to the shadow.
Negative values are ignored and zero means no blur (default).
- **`drop-shadow-offset-x`** and **`drop-shadow-offset-y`** (_length_): The horizontal and vertical distance
of the shadow from the element's frame. A negative value places the shadow left / above of the element.
- **`drop-shadow-color`** (_color_): The base color of the shadow to use. Typically that color is the starting color
of a gradient that fades into transparency.
- **`drop-shadow-blur`** (_length_): The radius of the shadow that also describes the level of blur applied to the shadow.
Negative values are ignored and zero means no blur (default).
The `drop-shadow` effect is supported for `Rectangle` elements.
@ -67,16 +67,16 @@ or smaller. The initial width can be controlled with the `preferred-width` prope
### Properties
* **`title`** (*string*): The window title that is shown in the title bar.
* **`icon`** (*image*): The window icon shown in the title bar or the task bar on window managers supporting it.
* **`no-frame`** (*bool*): Whether the window should be borderless/frameless or not.
* **`background`** (*color*): The background color of the Window. (default value: depends on the style)
* **`default-font-family`** (*string*): The font family to use as default in text elements inside this window, that don't
have their family set.
* **`default-font-size`** (*length*): The font size to use as default in text elements inside this window, that don't
have their size set.
* **`default-font-weight`** (*int*): The font weight to use as default in text elements inside this window, that don't
have their weight set. The values range from 100 (lightest) to 900 (thickest). 400 is the normal weight.
- **`title`** (_string_): The window title that is shown in the title bar.
- **`icon`** (_image_): The window icon shown in the title bar or the task bar on window managers supporting it.
- **`no-frame`** (_bool_): Whether the window should be borderless/frameless or not.
- **`background`** (_color_): The background color of the Window. (default value: depends on the style)
- **`default-font-family`** (_string_): The font family to use as default in text elements inside this window, that don't
have their family set.
- **`default-font-size`** (_length_): The font size to use as default in text elements inside this window, that don't
have their size set.
- **`default-font-weight`** (_int_): The font weight to use as default in text elements inside this window, that don't
have their weight set. The values range from 100 (lightest) to 900 (thickest). 400 is the normal weight.
## `Rectangle`
@ -87,13 +87,13 @@ When not part of a layout, its width or height defaults to 100% of the parent el
### Properties
* **`background`** (*brush*): The background brush of the Rectangle, typically a color. (default value: transparent)
* **`border-width`** (*length*): The width of the border. (default value: 0)
* **`border-color`** (*brush*): The color of the border. (default value: transparent)
* **`border-radius`** (*length*): The size of the radius. (default value: 0)
* **`clip`** (*bool*): By default, when an item is bigger or outside another item, it is still shown.
But when this property is set to `true`, then the children element of this Rectangle are going
to be clipped. (default: `false`)
- **`background`** (_brush_): The background brush of the Rectangle, typically a color. (default value: transparent)
- **`border-width`** (_length_): The width of the border. (default value: 0)
- **`border-color`** (_brush_): The color of the border. (default value: transparent)
- **`border-radius`** (_length_): The size of the radius. (default value: 0)
- **`clip`** (_bool_): By default, when an item is bigger or outside another item, it is still shown.
But when this property is set to `true`, then the children element of this Rectangle are going
to be clipped. (default: `false`)
### Example
@ -152,37 +152,39 @@ An Image can be used to represent an image loaded from an image file.
### Properties
* **`source`** (*image*): The image to load. In order to reference image, one uses the `@image-url("...")` macro
which loads the file relative to the directory containing the .slint file.
* **`source-clip-x`**, **`source-clip-y`**, **`source-clip-width`**, **`source-clip-height`** (*int*): Properties in source
image coordinates that define the region of the source image that is rendered. By default the entire source image is visible:
| Property | Default Binding |
|----------|---------------|
| `source-clip-x` | `0` |
| `source-clip-y` | `0` |
| `source-clip-width` | `source.width - source-clip-x` |
| `source-clip-height` | `source.height - source-clip-y` |
* **`image-fit`** (*enum*): Specifies how the source image shall be fit into the image element. Possible values are:
* `fill`: Scales and stretches the image to fit the width and height of the element.
* `contain`: The source image is scaled to fit into the image element's dimension while preserving the aspect ratio.
* `cover`: The source image is scaled to cover into the image element's dimension while preserving the aspect ratio.
- **`source`** (_image_): The image to load. In order to reference image, one uses the `@image-url("...")` macro
which loads the file relative to the directory containing the .slint file.
- **`source-clip-x`**, **`source-clip-y`**, **`source-clip-width`**, **`source-clip-height`** (_int_): Properties in source
image coordinates that define the region of the source image that is rendered. By default the entire source image is visible:
| Property | Default Binding |
|----------|---------------|
| `source-clip-x` | `0` |
| `source-clip-y` | `0` |
| `source-clip-width` | `source.width - source-clip-x` |
| `source-clip-height` | `source.height - source-clip-y` |
- **`image-fit`** (_enum_): Specifies how the source image shall be fit into the image element. Possible values are:
When the `Image` element is part of a layout, the default value for **`image-fit`** is `contain`. Otherwise it is `fill`.
- `fill`: Scales and stretches the image to fit the width and height of the element.
- `contain`: The source image is scaled to fit into the image element's dimension while preserving the aspect ratio.
- `cover`: The source image is scaled to cover into the image element's dimension while preserving the aspect ratio.
* **`image-rendering`** (*enum*): Specifies how the source image will be scaled. Possible values are:
* `smooth`: The image is scaled with a linear interpolation algorithm.
* `pixelated`: The image is scaled with the nearest neighbor algorithm.
When the `Image` element is part of a layout, the default value for **`image-fit`** is `contain`. Otherwise it is `fill`.
The default value is `smooth`.
- **`image-rendering`** (_enum_): Specifies how the source image will be scaled. Possible values are:
* **`colorize`** (*brush*): When set, the image is used as an alpha mask and is drown in the given color (or with the gradient)
* **`width`**, **`height`** (*length*): The width and height of the image as it appears on the screen.The default values are
the sizes provided by the **`source`** image. If the `Image` is **not** in a layout and only **one** of the two sizes are
specified, then the other defaults to the specified value scaled according to the aspect ratio of the **`source`** image.
- `smooth`: The image is scaled with a linear interpolation algorithm.
- `pixelated`: The image is scaled with the nearest neighbor algorithm.
* **`rotation-angle`** (*angle*), **`rotation-origin-x`** (*length*), **`rotation-origin-y`** (*length*):
Rotate the image by the given angle around the specified origin point. The default origin point is the center of the element.
When these properties are present, the Image cannot have any children elements.
The default value is `smooth`.
- **`colorize`** (_brush_): When set, the image is used as an alpha mask and is drown in the given color (or with the gradient)
- **`width`**, **`height`** (_length_): The width and height of the image as it appears on the screen.The default values are
the sizes provided by the **`source`** image. If the `Image` is **not** in a layout and only **one** of the two sizes are
specified, then the other defaults to the specified value scaled according to the aspect ratio of the **`source`** image.
- **`rotation-angle`** (_angle_), **`rotation-origin-x`** (_length_), **`rotation-origin-y`** (_length_):
Rotate the image by the given angle around the specified origin point. The default origin point is the center of the element.
When these properties are present, the Image cannot have any children elements.
### Example
@ -233,17 +235,17 @@ and the text itself.
### Properties
* **`text`** (*string*): The actual text.
* **`font-family`** (*string*): The font name
* **`font-size`** (*length*): The font size of the text
* **`font-weight`** (*int*): The weight of the font. The values range from 100 (lightest) to 900 (thickest). 400 is the normal weight.
* **`color`** (*brush*): The color of the text (default value: depends on the style)
* **`horizontal-alignment`** (*enum [`TextHorizontalAlignment`](builtin_enums.md#texthorizontalalignment)*): The horizontal alignment of the text.
* **`vertical-alignment`** (*enum [`TextVerticalAlignment`](builtin_enums.md#textverticalalignment)*): The vertical alignment of the text.
* **`wrap`** (*enum [`TextWrap`](builtin_enums.md#textwrap)*): The way the text wraps (default: no-wrap).
* **`overflow`** (*enum [`TextOverflow`](builtin_enums.md#textoverflow)*): What happens when the text overflows (default: clip).
* **`letter-spacing`** (*length*): The letter spacing allows changing the spacing between the glyphs. A positive value increases the spacing
and a negative value decreases the distance. The default value is 0.
- **`text`** (_string_): The actual text.
- **`font-family`** (_string_): The font name
- **`font-size`** (_length_): The font size of the text
- **`font-weight`** (_int_): The weight of the font. The values range from 100 (lightest) to 900 (thickest). 400 is the normal weight.
- **`color`** (_brush_): The color of the text (default value: depends on the style)
- **`horizontal-alignment`** (_enum [`TextHorizontalAlignment`](builtin_enums.md#texthorizontalalignment)_): The horizontal alignment of the text.
- **`vertical-alignment`** (_enum [`TextVerticalAlignment`](builtin_enums.md#textverticalalignment)_): The vertical alignment of the text.
- **`wrap`** (_enum [`TextWrap`](builtin_enums.md#textwrap)_): The way the text wraps (default: no-wrap).
- **`overflow`** (_enum [`TextOverflow`](builtin_enums.md#textoverflow)_): What happens when the text overflows (default: clip).
- **`letter-spacing`** (_length_): The letter spacing allows changing the spacing between the glyphs. A positive value increases the spacing
and a negative value decreases the distance. The default value is 0.
### Example
@ -289,8 +291,8 @@ When not part of a layout, its width or height defaults to 100% of the parent el
A path can be defined in two different ways:
* Using SVG path commands as a string
* Using path command elements in `.slint` markup.
- Using SVG path commands as a string
- Using path command elements in `.slint` markup.
The coordinates used in the geometric commands are within the imaginary coordinate system of the path.
When rendering on the screen, the shape is drawn relative to the `x` and `y` properties. If the `width`
@ -299,21 +301,22 @@ accordingly.
### Common Path Properties
* **`fill`** (*brush*): The color for filling the shape of the path.
* **`fill-rule`** (*enum [`FillRule`](builtin_enums.md#fillrule)*): The fill rule to use for the path. (default value: `nonzero`)
* **`stroke`** (*brush*): The color for drawing the outline of the path.
* **`stroke-width`** (*length*): The width of the outline.
* **`width`** (*length*): If non-zero, the path will be scaled to fit into the specified width.
* **`height`** (*length*): If non-zero, the path will be scaled to fit into the specified height.
* **`viewbox-x`**/**`viewbox-y`**/**`viewbox-width`**/**`viewbox-height`** (*float*) These four
properties allow defining the position and size of the viewport of the path in path coordinates.
- **`fill`** (_brush_): The color for filling the shape of the path.
- **`fill-rule`** (_enum [`FillRule`](builtin_enums.md#fillrule)_): The fill rule to use for the path. (default value: `nonzero`)
- **`stroke`** (_brush_): The color for drawing the outline of the path.
- **`stroke-width`** (_length_): The width of the outline.
- **`width`** (_length_): If non-zero, the path will be scaled to fit into the specified width.
- **`height`** (_length_): If non-zero, the path will be scaled to fit into the specified height.
- **`viewbox-x`**/**`viewbox-y`**/**`viewbox-width`**/**`viewbox-height`** (_float_) These four
properties allow defining the position and size of the viewport of the path in path coordinates.
If the `viewbox-width` or `viewbox-height` is less or equal than zero, the viewbox properties are
ignored and instead the bounding rectangle of all path elements is used to define the view port.
* **`clip`** (*bool*): By default, when a path has a view box defined and the elements render
outside of it, they are still rendered. When this property is set to `true`, then rendering will be
clipped at the boundaries of the view box.
This property must be a literal `true` or `false` (default: `false`)
If the `viewbox-width` or `viewbox-height` is less or equal than zero, the viewbox properties are
ignored and instead the bounding rectangle of all path elements is used to define the view port.
- **`clip`** (_bool_): By default, when a path has a view box defined and the elements render
outside of it, they are still rendered. When this property is set to `true`, then rendering will be
clipped at the boundaries of the view box.
This property must be a literal `true` or `false` (default: `false`)
#### Path Using SVG commands
@ -335,7 +338,7 @@ export component Example inherits Path {
The commands are provided in a property:
* **`commands`** (*string): A string providing the commands according to the SVG path specification.
- **`commands`** (\*string): A string providing the commands according to the SVG path specification.
#### Path Using SVG Path Elements
@ -383,8 +386,8 @@ will use this new position as their starting point, therefore this starts a new
###### Properties
* **`x`** (*float*): The x position of the new current point.
* **`y`** (*float*): The y position of the new current point.
- **`x`** (_float_): The x position of the new current point.
- **`y`** (_float_): The y position of the new current point.
##### `LineTo` Sub-element for `Path`
@ -393,8 +396,8 @@ location specified by the `x` and `y` properties.
###### Properties
* **`x`** (*float*): The target x position of the line.
* **`y`** (*float*): The target y position of the line.
- **`x`** (_float_): The target x position of the line.
- **`y`** (_float_): The target y position of the line.
##### `ArcTo` Sub-element for `Path`
@ -405,16 +408,16 @@ or angle.
###### Properties
* **`x`** (*float*): The target x position of the line.
* **`y`** (*float*): The target y position of the line.
* **`radius-x`** (*float*): The x-radius of the ellipse.
* **`radius-y`** (*float*): The y-radius of the ellipse.
* **`x-rotation`** (*float*): The x-axis of the ellipse will be rotated by the value of this
properties, specified in as angle in degrees from 0 to 360.
* **`large-arc`** (*bool*): Out of the two arcs of a closed ellipse, this flag selects that the
larger arc is to be rendered. If the property is `false`, the shorter arc is rendered instead.
* **`sweep`** (*bool*): If the property is `true`, the arc will be drawn as a clockwise turning arc;
anti-clockwise otherwise.
- **`x`** (_float_): The target x position of the line.
- **`y`** (_float_): The target y position of the line.
- **`radius-x`** (_float_): The x-radius of the ellipse.
- **`radius-y`** (_float_): The y-radius of the ellipse.
- **`x-rotation`** (_float_): The x-axis of the ellipse will be rotated by the value of this
properties, specified in as angle in degrees from 0 to 360.
- **`large-arc`** (_bool_): Out of the two arcs of a closed ellipse, this flag selects that the
larger arc is to be rendered. If the property is `false`, the shorter arc is rendered instead.
- **`sweep`** (_bool_): If the property is `true`, the arc will be drawn as a clockwise turning arc;
anti-clockwise otherwise.
##### `CubicTo` Sub-element for `Path`
@ -424,12 +427,12 @@ respective properties.
###### Properties
* **`x`** (*float*): The target x position of the curve.
* **`y`** (*float*): The target y position of the curve.
* **`control-1-x`** (*float*): The x coordinate of the curve's first control point.
* **`control-1-y`** (*float*): The y coordinate of the curve's first control point.
* **`control-2-x`** (*float*): The x coordinate of the curve's second control point.
* **`control-2-y`** (*float*): The y coordinate of the curve's second control point.
- **`x`** (_float_): The target x position of the curve.
- **`y`** (_float_): The target y position of the curve.
- **`control-1-x`** (_float_): The x coordinate of the curve's first control point.
- **`control-1-y`** (_float_): The y coordinate of the curve's first control point.
- **`control-2-x`** (_float_): The x coordinate of the curve's second control point.
- **`control-2-y`** (_float_): The y coordinate of the curve's second control point.
##### `QuadraticTo` Sub-element for `Path`
@ -439,10 +442,10 @@ location specified by the `x` and `y` properties, using the control points speci
###### Properties
* **`x`** (*float*): The target x position of the curve.
* **`y`** (*float*): The target y position of the curve.
* **`control-x`** (*float*): The x coordinate of the curve's control point.
* **`control-y`** (*float*): The y coordinate of the curve's control point.
- **`x`** (_float_): The target x position of the curve.
- **`y`** (_float_): The target y position of the curve.
- **`control-x`** (_float_): The x coordinate of the curve's control point.
- **`control-y`** (_float_): The y coordinate of the curve's control point.
##### `Close` Sub-element for `Path`
@ -458,17 +461,17 @@ When not part of a layout, its width or height default to 100% of the parent ele
### Properties
* **`pressed`** (*bool*): Set to `true` by the TouchArea when the mouse is pressed over it.
* **`has-hover`** (*bool*): Set to `true` by the TouchArea when the mouse is over it.
* **`mouse-x`**, **`mouse-y`** (*length*): Set by the TouchArea to the position of the mouse within it.
* **`pressed-x`**, **`pressed-y`** (*length*): Set to `true` by the TouchArea to the position of the mouse at the moment it was last pressed.
* **`mouse-cursor`** (*enum [`MouseCursor`](builtin_enums.md#mousecursor)*): The mouse cursor type when the mouse is hovering the TouchArea.
- **`pressed`** (_bool_): Set to `true` by the TouchArea when the mouse is pressed over it.
- **`has-hover`** (_bool_): Set to `true` by the TouchArea when the mouse is over it.
- **`mouse-x`**, **`mouse-y`** (_length_): Set by the TouchArea to the position of the mouse within it.
- **`pressed-x`**, **`pressed-y`** (_length_): Set to `true` by the TouchArea to the position of the mouse at the moment it was last pressed.
- **`mouse-cursor`** (_enum [`MouseCursor`](builtin_enums.md#mousecursor)_): The mouse cursor type when the mouse is hovering the TouchArea.
### Callbacks
* **`clicked`**: Emitted when clicked (the mouse is pressed, then released on this element)
* **`moved`**: The mouse has been moved. This will only be called if the mouse is also pressed.
* **`pointer-event(PointerEvent)`**: Received when a button was pressed or released.
- **`clicked`**: Emitted when clicked (the mouse is pressed, then released on this element)
- **`moved`**: The mouse has been moved. This will only be called if the mouse is also pressed.
- **`pointer-event(PointerEvent)`**: Received when a button was pressed or released.
### Example
@ -507,16 +510,16 @@ or it will be mapped to a private unicode character. The mapping of these non-pr
### Properties
* **`has-focus`** (*bool*): Set to `true` when item is focused and receives keyboard events.
- **`has-focus`** (_bool_): Set to `true` when item is focused and receives keyboard events.
### Methods
* **`focus()`** Call this function to focus the text input and make it receive future keyboard events.
- **`focus()`** Call this function to focus the text input and make it receive future keyboard events.
### Callbacks
* **`key-pressed(KeyEvent) -> EventResult`**: Emitted when a key is pressed, the argument is a `KeyEvent` struct
* **`key-released(KeyEvent) -> EventResult`**: Emitted when a key is released, the argument is a `KeyEvent` struct
- **`key-pressed(KeyEvent) -> EventResult`**: Emitted when a key is pressed, the argument is a `KeyEvent` struct
- **`key-released(KeyEvent) -> EventResult`**: Emitted when a key is released, the argument is a `KeyEvent` struct
### Example
@ -546,16 +549,16 @@ These layouts place their children next to each other vertically or horizontally
The size of elements can either be fixed with the `width` or `height` property, or if they are not set
they will be computed by the layout respecting the minimum and maximum sizes and the stretch factor.
## Properties
### Properties
* **`spacing`** (*length*): The distance between the elements in the layout.
* **`padding`** (*length*): the padding within the layout.
* **`padding-left`**, **`padding-right`**, **`padding-top`** and **`padding-bottom`** (*length*):
override the padding in specific sides.
* **`alignment`** (*FIXME enum*): Can be one of `stretch`, `center`, `start`, `end`,
`space-between`, `space-around`. Defaults to `stretch`. Matches the CSS flex.
- **`spacing`** (_length_): The distance between the elements in the layout.
- **`padding`** (_length_): the padding within the layout.
- **`padding-left`**, **`padding-right`**, **`padding-top`** and **`padding-bottom`** (_length_):
override the padding in specific sides.
- **`alignment`** (_FIXME enum_): Can be one of `stretch`, `center`, `start`, `end`,
`space-between`, `space-around`. Defaults to `stretch`. Matches the CSS flex.
## Example
### Example
```slint
export component Foo inherits Window {
@ -580,10 +583,10 @@ Alternatively, the item can be put in a `Row` element.
### Properties
* **`spacing`** (*length*): The distance between the elements in the layout.
* **`padding`** (*length*): the padding within the layout.
* **`padding-left`**, **`padding-right`**, **`padding-top`** and **`padding-bottom`** (*length*):
override the padding in specific sides.
- **`spacing`** (_length_): The distance between the elements in the layout.
- **`padding`** (_length_): the padding within the layout.
- **`padding-left`**, **`padding-right`**, **`padding-top`** and **`padding-bottom`** (_length_):
override the padding in specific sides.
### Examples
@ -638,9 +641,9 @@ When not part of a layout, its width or height defaults to 100% of the parent el
### Properties
* **`viewport-height`**, **`viewport-width`** (*length*): The total size of the scrollable element
* **`viewport-x`**, **`viewport-y`** (*length*): The position of the scrollable element relative to the Flickable. This is usually a negative value.
* **`interactive`** (*bool*): When true, the viewport can be scrolled by clicking on it and dragging it with the cursor. (default: true)
- **`viewport-height`**, **`viewport-width`** (_length_): The total size of the scrollable element
- **`viewport-x`**, **`viewport-y`** (_length_): The position of the scrollable element relative to the Flickable. This is usually a negative value.
- **`interactive`** (_bool_): When true, the viewport can be scrolled by clicking on it and dragging it with the cursor. (default: true)
### Example
@ -668,31 +671,31 @@ When not part of a layout, its width or height defaults to 100% of the parent el
### Properties
* **`text`** (*string*): The actual text.
* **`font-family`** (*string*): The font name
* **`font-size`** (*length*): The font size of the text
* **`font-weight`** (*int*): The weight of the font. The values range from 100 (lightest) to 900 (thickest). 400 is the normal weight.
* **`color`** (*brush*): The color of the text (default value: depends on the style)
* **`horizontal-alignment`** (*enum [`TextHorizontalAlignment`](builtin_enums.md#texthorizontalalignment)*): The horizontal alignment of the text.
* **`vertical-alignment`** (*enum [`TextVerticalAlignment`](builtin_enums.md#textverticalalignment)*): The vertical alignment of the text.
* **`has-focus`** (*bool*): Set to `true` when item is focused and receives keyboard events.
* **`letter-spacing`** (*length*): The letter spacing allows changing the spacing between the glyphs. A positive value increases the spacing
and a negative value decreases the distance. The default value is 0.
* **`single-line`** (*bool*): When set to `true`, no newlines are allowed (default value: `true`)
* **`read-only`** (*bool*): When set to `true`, text editing via keyboard and mouse is disabled but
selecting text is still enabled as well as editing text programatically (default value: `false`)
* **`wrap`** (*enum [`TextWrap`](builtin_enums.md#textwrap)*): The way the text input wraps. Only makes sense when `single-line` is false. (default: no-wrap)
* **`input-type`** (*enum [`InputType`](builtin_enums.md#InputType)*): The way to allow special input viewing properties such as password fields (default value: `text`).
- **`text`** (_string_): The actual text.
- **`font-family`** (_string_): The font name
- **`font-size`** (_length_): The font size of the text
- **`font-weight`** (_int_): The weight of the font. The values range from 100 (lightest) to 900 (thickest). 400 is the normal weight.
- **`color`** (_brush_): The color of the text (default value: depends on the style)
- **`horizontal-alignment`** (_enum [`TextHorizontalAlignment`](builtin_enums.md#texthorizontalalignment)_): The horizontal alignment of the text.
- **`vertical-alignment`** (_enum [`TextVerticalAlignment`](builtin_enums.md#textverticalalignment)_): The vertical alignment of the text.
- **`has-focus`** (_bool_): Set to `true` when item is focused and receives keyboard events.
- **`letter-spacing`** (_length_): The letter spacing allows changing the spacing between the glyphs. A positive value increases the spacing
and a negative value decreases the distance. The default value is 0.
- **`single-line`** (_bool_): When set to `true`, no newlines are allowed (default value: `true`)
- **`read-only`** (_bool_): When set to `true`, text editing via keyboard and mouse is disabled but
selecting text is still enabled as well as editing text programatically (default value: `false`)
- **`wrap`** (_enum [`TextWrap`](builtin_enums.md#textwrap)_): The way the text input wraps. Only makes sense when `single-line` is false. (default: no-wrap)
- **`input-type`** (_enum [`InputType`](builtin_enums.md#InputType)_): The way to allow special input viewing properties such as password fields (default value: `text`).
### Methods
* **`focus()`** Call this function to focus the text input and make it receive future keyboard events.
- **`focus()`** Call this function to focus the text input and make it receive future keyboard events.
### Callbacks
* **`accepted()`**: Emitted when enter key is pressed
* **`edited()`**: Emitted when the text has changed because the user modified it
* **`cursor-position-changed(Point)`**: The cursor was moved to the new (x, y) position
- **`accepted()`**: Emitted when enter key is pressed
- **`edited()`**: Emitted when the text has changed because the user modified it
- **`cursor-position-changed(Point)`**: The cursor was moved to the new (x, y) position
### Example
@ -715,7 +718,7 @@ Note: It is not allowed to access properties of elements within the popup from o
### Methods
* **`show()`** Call this function to show the popup.
- **`show()`** Call this function to show the popup.
### Example
@ -757,8 +760,8 @@ When viewed with the `slint-viewer` program, the `ok`, `cancel`, and `close` but
### Properties
* **`title`** (*string*): The window title that is shown in the title bar.
* **`icon`** (*image*): The window icon shown in the title bar or the task bar on window managers supporting it.
- **`title`** (_string_): The window title that is shown in the title bar.
- **`icon`** (_image_): The window icon shown in the title bar or the task bar on window managers supporting it.
### Example
@ -776,116 +779,3 @@ export component Example inherits Dialog {
}
}
```
# Builtin Structures
## `Point`
This structure represents a point with x and y coordinate
### Fields
* **`x`** (*length*)
* **`y`** (*length*)
## `KeyEvent`
This structure is generated and passed to the key press and release
callbacks of the `FocusScope` element.
### Fields
* **`text`** (*string*): The string representation of the key
* **`modifiers`** (*KeyboardModifiers*): The keyboard modifiers pressed during the event
## `KeyboardModifiers`
This structure is generated as part of `KeyEvent`, to indicate which modifier keys
are pressed during the generation of a key event.
### Fields
* **`control`** (*bool*): `true` if the control key is pressed. On macOS this corresponds to the command key.
* **`alt`** (*bool*): `true` if alt key is pressed.
* **`shift`** (*bool*): `true` if the shift key is pressed.
* **`meta`** (*bool*): `true` if the windows key is pressed on Windows, or the control key on macOS.
## `PointerEvent`
This structure is generated and passed to the `pointer-event` callback of the `TouchArea` element.
### Fields
* **`kind`** (*enum PointerEventKind*): The kind of the event: one of the following
- `down`: The button was pressed.
- `up`: The button was released.
- `cancel`: Another element or window took hold of the grab. This applies to all pressed button and the `button` is not relevent.
* **`button`** (*enum PointerEventButton*): The button that was pressed or released. `left`, `right`, `middle`, or `none`.
# Namespaces
The following namespaces provide access to common constants such as special keys or named colors.
## `Key`
Use the constants in the `Key` namespace to handle pressing of keys that don't have a printable character. Check the value of [`KeyEvent`](#keyevent)'s `text` property
against the constants below.
* **`Backspace`**
* **`Tab`**
* **`Return`**
* **`Escape`**
* **`Backtab`**
* **`Delete`**
* **`Shift`**
* **`Control`**
* **`Alt`**
* **`AltGr`**
* **`CapsLock`**
* **`ShiftR`**
* **`ControlR`**
* **`Meta`**
* **`MetaR`**
* **`UpArrow`**
* **`DownArrow`**
* **`LeftArrow`**
* **`RightArrow`**
* **`F1`**
* **`F2`**
* **`F3`**
* **`F4`**
* **`F5`**
* **`F6`**
* **`F7`**
* **`F8`**
* **`F9`**
* **`F10`**
* **`F11`**
* **`F12`**
* **`F13`**
* **`F14`**
* **`F15`**
* **`F16`**
* **`F17`**
* **`F18`**
* **`F19`**
* **`F20`**
* **`F21`**
* **`F22`**
* **`F23`**
* **`F24`**
* **`Insert`**
* **`Home`**
* **`End`**
* **`PageUp`**
* **`PageDown`**
* **`ScrollLock`**
* **`Pause`**
* **`SysReq`**
* **`Stop`**
* **`Menu`**
## `Colors`
Use the colors namespace to select colors by their name. For example you can use `Colors.aquamarine` or `Colors.bisque`.
The entire list of names is very long. You can find a complete list in the [CSS Specification](https://www.w3.org/TR/css-color-3/#svg-color).

16
docs/langref/src/builtin_functions.md
View file

@ -1,12 +1,10 @@
# Builtin functions
# Builtin Functions
* **`debug(string) -> string`**
## `animation-tick() -> duration`
The debug function take a string as an argument and prints it
* **`animation-tick() -> duration`**: This function returns a monotonically increasing time, which can be used for animations.
Calling this function from a binding will constantly re-evaluate the binding.
It can be used like so: `x: 1000px + sin(animation-tick() / 1s * 360deg) * 100px;` or `y: 20px * mod(animation-tick(), 2s) / 2s `
This function returns a monotonically increasing time, which can be used for animations.
Calling this function from a binding will constantly re-evaluate the binding.
It can be used like so: `x: 1000px + sin(animation-tick() / 1s * 360deg) * 100px;` or `y: 20px * mod(animation-tick(), 2s) / 2s `
```slint
export component Example inherits Window {
@ -28,3 +26,7 @@ export component Example inherits Window {
}
}
```
## `debug(string) -> string`
The debug function take a string as an argument and prints it

120
docs/langref/src/builtin_namespaces.md Normal file
View file

@ -0,0 +1,120 @@
# Builtin Namespaces
The following namespaces provide access to common constants such as special keys or named colors.
## `Colors` Namespace
Use the colors namespace to select colors by their name. For example you can use `Colors.aquamarine` or `Colors.bisque`.
The entire list of names is very long. You can find a complete list in the [CSS Specification](https://www.w3.org/TR/css-color-3/#svg-color).
These functions are available both in the global scope, and in the `Colors` namespace.
- **`rgb(int, int, int) -> color`**, **`rgba(int, int, int, float) -> color`**
Return the color as in CSS. Like in CSS, these two functions are actually aliases that can take
three or four parameters.
The first 3 parameters can be either number between 0 and 255, or a percentage with a `%` unit.
The fourth value, if present, is an alpha value between 0 and 1.
Unlike in CSS, the commas are mandatory.
## `Key` Namespace
Use the constants in the `Key` namespace to handle pressing of keys that don't have a printable character. Check the value of [`KeyEvent`](#keyevent)'s `text` property
against the constants below.
- **`Backspace`**
- **`Tab`**
- **`Return`**
- **`Escape`**
- **`Backtab`**
- **`Delete`**
- **`Shift`**
- **`Control`**
- **`Alt`**
- **`AltGr`**
- **`CapsLock`**
- **`ShiftR`**
- **`ControlR`**
- **`Meta`**
- **`MetaR`**
- **`UpArrow`**
- **`DownArrow`**
- **`LeftArrow`**
- **`RightArrow`**
- **`F1`**
- **`F2`**
- **`F3`**
- **`F4`**
- **`F5`**
- **`F6`**
- **`F7`**
- **`F8`**
- **`F9`**
- **`F10`**
- **`F11`**
- **`F12`**
- **`F13`**
- **`F14`**
- **`F15`**
- **`F16`**
- **`F17`**
- **`F18`**
- **`F19`**
- **`F20`**
- **`F21`**
- **`F22`**
- **`F23`**
- **`F24`**
- **`Insert`**
- **`Home`**
- **`End`**
- **`PageUp`**
- **`PageDown`**
- **`ScrollLock`**
- **`Pause`**
- **`SysReq`**
- **`Stop`**
- **`Menu`**
## `Math` Namespace
These functions are available both in the global scope and in the `Math` namespace.
### `abs(float) -> float`
Return the absolute value.
### `acos(float) -> angle`, `asin(float) -> angle`, `atan(float) -> angle`, `cos(angle) -> float`, `sin(angle) -> float`, `tan(angle) -> float`
The trigonometry function. Note that the should be typed with `deg` or `rad` unit
(for example `cos(90deg)` or `sin(slider.value * 1deg)`).
### `ceil(float) -> int` and `floor(float) -> int`
Return the ceiling or floor
### `log(float, float) -> float`
Return the log of the first value with a base of the second value
### `max(T, T) -> T` and `min(T, T) -> T`
Return the arguments with the minimum (or maximum) value. All arguments must be of the same numeric type
### `mod(T, T) -> T`
Perform a modulo operation, where T is some numeric type.
### `round(float) -> int`
Return the value rounded to the nearest integer
### `sqrt(float) -> float`
Square root
### `pow(float, float) -> float`
Return the value of the first value raised to the second

64
docs/langref/src/builtin_structs.md Normal file
View file

@ -0,0 +1,64 @@
# Builtin Structures
## `KeyboardModifiers`
This structure is generated as part of `KeyEvent`, to indicate which modifier keys
are pressed during the generation of a key event.
### Fields
- **`control`** (_bool_): `true` if the control key is pressed. On macOS this corresponds to the command key.
- **`alt`** (_bool_): `true` if alt key is pressed.
- **`shift`** (_bool_): `true` if the shift key is pressed.
- **`meta`** (_bool_): `true` if the windows key is pressed on Windows, or the control key on macOS.
## `KeyEvent`
This structure is generated and passed to the key press and release
callbacks of the `FocusScope` element.
### Fields
- **`text`** (_string_): The string representation of the key
- **`modifiers`** (_KeyboardModifiers_): The keyboard modifiers pressed during the event
## `Point`
This structure represents a point with x and y coordinate
### Fields
- **`x`** (_length_)
- **`y`** (_length_)
## `PointerEvent`
This structure is generated and passed to the `pointer-event` callback of the `TouchArea` element.
### Fields
- **`kind`** (_enum PointerEventKind_): The kind of the event: one of the following
- `down`: The button was pressed.
- `up`: The button was released.
- `cancel`: Another element or window took hold of the grab. This applies to all pressed button and the `button` is not relevent.
- **`button`** (_enum PointerEventButton_): The button that was pressed or released. `left`, `right`, `middle`, or `none`.
## `StandardListViewItem`
The `StandardListViewItem` is used to display items in the `StandardListView` and the `StandardTableView`.
### Fields
- **`text`** (_string_): Describes the text of the item.
## `TableColumn`
`TableColumn` is used to define the column and the column header of a TableView.
### Fields
- **`title`** (_string_): Describes the column header title.
- **`min-width`** (_length_): Defines the minimum with of the column.
- **`width`** (_length_): The current width of the column.
- **`horizontal-stretch`** (_float_): Defines the horizontal stretch of the column.
- **`sort-order`** (_`SortOrder`_): Describes the sort order of the column.

10
docs/langref/src/callback_alias.md
View file

@ -1,10 +0,0 @@
## Callback aliases
It is possible to declare callback aliases in a similar way to two-way bindings:
```slint,no-preview
export component Example inherits Rectangle {
callback clicked <=> area.clicked;
area := TouchArea {}
}
```

13
docs/langref/src/callback.md → docs/langref/src/callbacks.md
View file

@ -1,4 +1,4 @@
# Callback
# Callbacks
Components may declare callbacks, that communicate changes of state
to the outside. Callbacks are invoked by "calling" them like you would
@ -45,3 +45,14 @@ export component Example inherits Rectangle {
hello(aa, bb) => { aa + bb }
}
```
## Callback aliases
It is possible to declare callback aliases in a similar way to two-way bindings:
```slint,no-preview
export component Example inherits Rectangle {
callback clicked <=> area.clicked;
area := TouchArea {}
}
```

1
docs/langref/src/chapter_1.md
View file

@ -1 +0,0 @@
# Chapter 1

13
docs/langref/src/colors.md
View file

@ -1,13 +0,0 @@
## `Colors` namespace
These functions are available both in the global scope, and in the `Colors` namespace.
* **`rgb(int, int, int) -> color`**, **`rgba(int, int, int, float) -> color`**
Return the color as in CSS. Like in CSS, these two functions are actually aliases that can take
three or four parameters.
The first 3 parameters can be either number between 0 and 255, or a percentage with a `%` unit.
The fourth value, if present, is an alpha value between 0 and 1.
Unlike in CSS, the commas are mandatory.

53
docs/langref/src/file_format.md → docs/langref/src/concepts.md
View file

@ -1,4 +1,6 @@
# `.slint` Files
# Concepts
## `.slint` Files
Each `.slint` file defines one or several components. These components declare
a tree of elements. Each declared component may be used under its
@ -67,8 +69,51 @@ Names have to be valid [identifiers](identifiers.md).
Some elements are also accessible under pre-defined names:
- `root` refers to the outermost element of a component.
- `self` refers to the current element.
- `parent` refers to the parent element of the current element.
- `root` refers to the outermost element of a component.
- `self` refers to the current element.
- `parent` refers to the parent element of the current element.
These names are reserved and can't be re-defined by the user.
## Container Components
When creating components, it may sometimes be useful to influence where child elements
are placed when they are used. For example, imagine a component that draws a label above
whatever element the user places inside:
```slint,ignore
export component MyApp inherits Window {
BoxWithLabel {
Text {
// ...
}
}
// ...
}
```
Such a `BoxWithLabel` could be implemented using a layout, but by default child elements like
the `Text` element become children of the `BoxWithLabel`, when they would have to be somewhere
else, inside the layout. For this purpose, you can change the default child placement by using
the `@children` expression inside the element hierarchy of a component:
```slint
component BoxWithLabel inherits GridLayout {
Row {
Text { text: "label text here"; }
}
Row {
@children
}
}
export component MyApp inherits Window {
preferred-height: 100px;
BoxWithLabel {
Rectangle { background: blue; }
Rectangle { background: yellow; }
}
}
```

0
docs/langref/src/condition.md → docs/langref/src/conditions.md
View file

42
docs/langref/src/containers.md
View file

@ -1,42 +0,0 @@
## Container Components
When creating components, it may sometimes be useful to influence where child elements
are placed when they are used. For example, imagine a component that draws a label above
whatever element the user places inside:
```slint,ignore
export component MyApp inherits Window {
BoxWithLabel {
Text {
// ...
}
}
// ...
}
```
Such a `BoxWithLabel` could be implemented using a layout, but by default child elements like
the `Text` element become children of the `BoxWithLabel`, when they would have to be somewhere
else, inside the layout. For this purpose, you can change the default child placement by using
the `@children` expression inside the element hierarchy of a component:
```slint
component BoxWithLabel inherits GridLayout {
Row {
Text { text: "label text here"; }
}
Row {
@children
}
}
export component MyApp inherits Window {
preferred-height: 100px;
BoxWithLabel {
Rectangle { background: blue; }
Rectangle { background: yellow; }
}
}
```

14
docs/langref/src/intro.md
View file

@ -1,14 +0,0 @@
# The `.slint` Language Reference
The Slint design markup language describes extensible graphical user interfaces.
- Place and compose a tree of visual elements in a window using a textual representation.
- Configure the appearance of elements via properties. For example a `Text` element has `text`
properties, while a `Rectangle` element has a `background` color.
- Assign binding expressions to properties to automatically compute values that depend on other properties.
- Group binding expressions together with named states and conditions.
- Declare animations on properties and states to make the user interface feel alive.
- Build your own re-usable components and share them in `.slint` module files.
- Define data structures and models and access them from programming languages.
- Build highly customized user interfaces with the [builtin elements](builtin_elements.md)
and pre-built [widgets](widgets.md) provided.

29
docs/langref/src/lin_gradients.md
View file

@ -1,29 +0,0 @@
### Linear Gradients
Linear gradients describe smooth, colorful surfaces. They're specified using an angle and a series of
color stops. The colors will be linearly interpolated between the stops, aligned to an imaginary line
that is rotated by the specified angle. This is called a linear gradient and is specified using the
`@linear-gradient` macro with the following signature:
**`@linear-gradient(angle, color percentage, color percentage, ...)`**
The first parameter to the macro is an angle (see [Types](#types)). The gradient line's starting point
will be rotated by the specified value.
Following the initial angle is one or multiple color stops, describe as a space separated pair of a
`color` value and a `percentage`. The color specifies which value the linear color interpolation should
reach at the specified percentage along the axis of the gradient.
The following example shows a rectangle that's filled with a linear gradient that starts with a light blue
color, interpolates to a very light shade in the center and finishes with an orange tone:
```slint
export component Example inherits Window {
preferred-width: 100px;
preferred-height: 100px;
Rectangle {
background: @linear-gradient(90deg, #3f87a6 0%, #ebf8e1 50%, #f69d3c 100%);
}
}
```

40
docs/langref/src/math.md
View file

@ -1,40 +0,0 @@
## `Math` namespace
These functions are available both in the global scope and in the `Math` namespace.
* **`min`**, **`max`**
Return the arguments with the minimum (or maximum) value. All arguments must be of the same numeric type
* **`mod(T, T) -> T`**
Perform a modulo operation, where T is some numeric type.
* **`abs(float) -> float`**
Return the absolute value.
* **`round(float) -> int`**
Return the value rounded to the nearest integer
* **`ceil(float) -> int`**, **`floor(float) -> int`**
Return the ceiling or floor
* **`sin(angle) -> float`**, **`cos(angle) -> float`**, **`tan(angle) -> float`**, **`asin(float) -> angle`**, **`acos(float) -> angle`**, **`atan(float) -> angle`**
The trigonometry function. Note that the should be typed with `deg` or `rad` unit
(for example `cos(90deg)` or `sin(slider.value * 1deg)`).
* **`sqrt(float) -> float`**
Square root
* **`pow(float, float) -> float`**
Return the value of the first value raised to the second
* **`log(float, float) -> float`**
Return the log of the first value with a base of the second value

25
docs/langref/src/module_syntax.md
View file

@ -1,25 +0,0 @@
## Module Syntax
The following syntax is supported for importing types:
```slint,ignore
import { export1 } from "module.slint";
import { export1, export2 } from "module.slint";
import { export1 as alias1 } from "module.slint";
import { export1, export2 as alias2, /* ... */ } from "module.slint";
```
The following syntax is supported for exporting types:
```slint,ignore
// Export declarations
export component MyButton inherits Rectangle { /* ... */ }
// Export lists
component MySwitch inherits Rectangle { /* ... */ }
export { MySwitch };
export { MySwitch as Alias1, MyButton as Alias2 };
// Re-export all types from other module
export * from "other_module.slint";
```

26
docs/langref/src/modules.md
View file

@ -83,3 +83,29 @@ other files:
import { Logic as MathLogic } from "math.slint";
export { MathLogic } // known as "MathLogic" when using native APIs to access globals
```
## Module Syntax
The following syntax is supported for importing types:
```slint,ignore
import { export1 } from "module.slint";
import { export1, export2 } from "module.slint";
import { export1 as alias1 } from "module.slint";
import { export1, export2 as alias2, /* ... */ } from "module.slint";
```
The following syntax is supported for exporting types:
```slint,ignore
// Export declarations
export component MyButton inherits Rectangle { /* ... */ }
// Export lists
component MySwitch inherits Rectangle { /* ... */ }
export { MySwitch };
export { MySwitch as Alias1, MyButton as Alias2 };
// Re-export all types from other module
export * from "other_module.slint";
```

91
docs/langref/src/properties.md
View file

@ -55,3 +55,94 @@ export component Button {
All properties declared at the top level of a component that are not `private` are accessible from the outside when using a component as an element, or via the
language bindings from the business logic.
## Bindings
The binding expression is automatically re-evaluated when properties accessed in the expression change.
In the following example, the text of the button automatically changes when
the user presses the button. Incrementing the `counter` property automatically
invalidates the expression bound to `text` and triggers a re-evaluation.
```slint
import { Button } from "std-widgets.slint";
export component Example inherits Window {
preferred-width: 50px;
preferred-height: 50px;
Button {
property <int> counter: 3;
clicked => { self.counter += 3 }
text: self.counter * 2;
}
}
```
The re-evaluation happens lazily when the property is queried.
Internally, a dependency is registered for any property accessed while evaluating a binding.
When a property changes, the dependencies are notified and all dependent bindings
are marked as dirty.
Callbacks in native code by default don't depend on any properties unless they query a property in the native code.
## Two-way Bindings
Create two-way bindings between properties with the `<=>` syntax. These properties will be linked
together and always contain the same value.
The right hand side of the `<=>` must be a reference to a property of the same type.
The property type is optional with two-way bindings, it will be inferred if not specified.
```slint,no-preview
export component Example {
in property<brush> rect-color <=> r.background;
// it is allowed to omit the type to have it automatically inferred
in property rect-color2 <=> r.background;
r:= Rectangle {
width: parent.width;
height: parent.height;
background: blue;
}
}
```
## Relative Lengths
Sometimes it's convenient to express the relationships of length properties in terms of relative percentages.
For example the following inner blue rectangle has half the size of the outer green window:
```slint
export component Example inherits Window {
preferred-width: 100px;
preferred-height: 100px;
background: green;
Rectangle {
background: blue;
width: parent.width * 50%;
height: parent.height * 50%;
}
}
```
This pattern of expressing the `width` or `height` in percent of the parent's property with the same name is
common. For convenience, a short-hand syntax exists for this scenario:
- The property is `width` or `height`
- A binding expression evaluates to a percentage.
If these conditions are met, then it's not necessary to specify the parent property, instead you can simply
use the percentage. The earlier example then looks like this:
```slint
export component Example inherits Window {
preferred-width: 100px;
preferred-height: 100px;
background: green;
Rectangle {
background: blue;
width: 50%;
height: 50%;
}
}
```

21
docs/langref/src/rad_gradients.md
View file

@ -1,21 +0,0 @@
### Radial Gradients
Linear gradiants are like real gradiant but the colors is interpolated in a circle instead of
along a line. To describe a readial gradiant, use the `@radial-gradient` macro with the following signature:
**`@radial-gradient(circle, color percentage, color percentage, ...)`**
The first parameter to the macro is always `circle` because only circular radients are supported.
The syntax is otherwise based on the CSS `radial-gradient` function.
Example:
```slint
export component Example inherits Window {
preferred-width: 100px;
preferred-height: 100px;
Rectangle {
background: @radial-gradient(circle, #f00 0%, #0f0 50%, #00f 100%);
}
}
```

41
docs/langref/src/rel-length.md
View file

@ -1,41 +0,0 @@
## Relative Lengths
Sometimes it's convenient to express the relationships of length properties in terms of relative percentages.
For example the following inner blue rectangle has half the size of the outer green window:
```slint
export component Example inherits Window {
preferred-width: 100px;
preferred-height: 100px;
background: green;
Rectangle {
background: blue;
width: parent.width * 50%;
height: parent.height * 50%;
}
}
```
This pattern of expressing the `width` or `height` in percent of the parent's property with the same name is
common. For convenience, a short-hand syntax exists for this scenario:
- The property is `width` or `height`
- A binding expression evaluates to a percentage.
If these conditions are met, then it's not necessary to specify the parent property, instead you can simply
use the percentage. The earlier example then looks like this:
```slint
export component Example inherits Window {
preferred-width: 100px;
preferred-height: 100px;
background: green;
Rectangle {
background: blue;
width: 50%;
height: 50%;
}
}
```

0
docs/langref/src/repetition.md → docs/langref/src/repetitions.md
View file

36
docs/langref/src/states.md
View file

@ -35,3 +35,39 @@ export component Example inherits Window {
In this example, the `active` and `active-hovered` states are defined depending on the value of the `active`
boolean property and the `TouchArea`'s `has-hover`. When the user hovers the example with the mouse, it will toggle between a blue and a green background,
and adjust the text label accordingly. Clicking toggles the `active` property and thus enters the `inactive` state.
## Transitions
Transitions bind animations to state changes.
This example defines two transitions. First the `out` keyword is used to animate
all properties for 800ms when leaving the `disabled` state. The second
transition uses the `in` keyword to animate the background when transitioning
into the `down` state.
```slint
export component Example inherits Window {
preferred-width: 100px;
preferred-height: 100px;
text := Text { text: "hello"; }
in-out property<bool> pressed;
in-out property<bool> is-enabled;
states [
disabled when !root.is-enabled : {
background: gray; // same as root.background: gray;
text.color: white;
out {
animate * { duration: 800ms; }
}
}
down when pressed : {
background: blue;
in {
animate background { duration: 300ms; }
}
}
]
}
```

35
docs/langref/src/tranitions.md
View file

@ -1,35 +0,0 @@
## Transitions
Transitions bind animations to state changes.
This example defines two transitions. First the `out` keyword is used to animate
all properties for 800ms when leaving the `disabled` state. The second
transition uses the `in` keyword to animate the background when transitioning
into the `down` state.
```slint
export component Example inherits Window {
preferred-width: 100px;
preferred-height: 100px;
text := Text { text: "hello"; }
in-out property<bool> pressed;
in-out property<bool> is-enabled;
states [
disabled when !root.is-enabled : {
background: gray; // same as root.background: gray;
text.color: white;
out {
animate * { duration: 800ms; }
}
}
down when pressed : {
background: blue;
in {
animate background { duration: 300ms; }
}
}
]
}
```

28
docs/langref/src/types.md
View file

@ -1,6 +1,6 @@
# Types
All properties in elements have a type. The following types are supported:
All properties in Slint have a type. Slint knows these basic types:
| Type | Description |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
@ -9,7 +9,7 @@ All properties in elements have a type. The following types are supported:
| `bool` | boolean whose value can be either `true` or `false`. |
| `string` | UTF-8 encoded, reference counted string. |
| `color` | RGB color with an alpha channel, with 8 bit precision for each channel. CSS color names as well as the hexadecimal color encodings are supported, such as `#RRGGBBAA` or `#RGB`. |
| `brush` | A brush is a special type that can be either initialized from a color or a gradient specification. See the [Colors and Brushes Section](brushes.md#colors-and-brushes) for more information. |
| `brush` | A brush is a special type that can be either initialized from a color or a gradient specification. See the [Colors and Brushes Section](brushes.md#colors-and-brushes) for more information. |
| `physical-length` | This is an amount of physical pixels. To convert from an integer to a length unit, one can simply multiply by `1px`. Or to convert from a length to a float, one can divide by `1phx`. |
| `length` | The type used for `x`, `y`, `width` and `height` coordinates. Corresponds to a literal like `1px`, `1pt`, `1in`, `1mm`, or `1cm`. It can be converted to and from length provided the binding is run in a context where there is an access to the device pixel ratio. |
| `duration` | Type for the duration of animations. A suffix like `ms` (millisecond) or `s` (second) is used to indicate the precision. |
@ -20,3 +20,27 @@ All properties in elements have a type. The following types are supported:
| `relative-font-size` | Relative font size factor that is multiplied with the `Window.default-font-size` and can be converted to a `length`. |
Please see the language specific API references how these types are mapped to the APIs of the different programming languages.
```{include} strings.md
```
```{include} brushes.md
```
```{include} images.md
```
```{include} structs.md
```
```{include} models.md
```
```{include} conversions.md
```

164
docs/langref/src/widgets.md
View file

@ -4,11 +4,11 @@ Slint provides a series of built-in widgets that can be imported from `"std-widg
The widget appearance depends on the selected style. The following styles are available:
* `fluent`: The **Fluent** style implements the [Fluent Design System](https://www.microsoft.com/design/fluent/).
* `material`: The **Material** style implements the [Material Design](https://m3.material.io).
* `native`: The **Native** style resembles the appearance of the controls that are native to the platform they
are used on. This specifically includes support for the look and feel of controls on macOS and Windows. This
style is only available if you have Qt installed on your system.
- `fluent`: The **Fluent** style implements the [Fluent Design System](https://www.microsoft.com/design/fluent/).
- `material`: The **Material** style implements the [Material Design](https://m3.material.io).
- `native`: The **Native** style resembles the appearance of the controls that are native to the platform they
are used on. This specifically includes support for the look and feel of controls on macOS and Windows. This
style is only available if you have Qt installed on your system.
See [Selecting a Widget Style](#selecting-a-widget-style) for details how to select the style. If no style is selected, `native` is the default. If `native` is not available, `fluent` is the default.
@ -16,16 +16,16 @@ See [Selecting a Widget Style](#selecting-a-widget-style) for details how to sel
### Properties
* **`checkable`** (*bool*): Shows whether the button can be checked or not. This enables the `checked` property to possibly become `true`.
* **`checked`** (*bool*): Shows whether the button is checked or not. Needs `checkable` to be `true` to work.
* **`enabled`**: (*bool*): Defaults to true. When false, the button cannot be pressed
* **`icon`** (*image*): The image to show in the button. Note that not all styles support drawing icons.
* **`pressed`**: (*bool*): Set to true when the button is pressed.
* **`text`** (*string*): The text written in the button.
- **`checkable`** (_bool_): Shows whether the button can be checked or not. This enables the `checked` property to possibly become `true`.
- **`checked`** (_bool_): Shows whether the button is checked or not. Needs `checkable` to be `true` to work.
- **`enabled`**: (_bool_): Defaults to true. When false, the button cannot be pressed
- **`icon`** (_image_): The image to show in the button. Note that not all styles support drawing icons.
- **`pressed`**: (_bool_): Set to true when the button is pressed.
- **`text`** (_string_): The text written in the button.
### Callbacks
* **`clicked`**
- **`clicked`**
### Example
@ -48,13 +48,13 @@ it can used one of the pre-defined `kind` and the text and icon will depend on t
### Properties
* **`kind`** (*enum*): The kind of button, one of
`ok` `cancel`, `apply`, `close`, `reset`, `help`, `yes`, `no,` `abort`, `retry` or `ignore`
* **`enabled`**: (*bool*): Defaults to true. When false, the button cannot be pressed
- **`kind`** (_enum_): The kind of button, one of
`ok` `cancel`, `apply`, `close`, `reset`, `help`, `yes`, `no,` `abort`, `retry` or `ignore`
- **`enabled`**: (_bool_): Defaults to true. When false, the button cannot be pressed
### Callbacks
* **`clicked`**
- **`clicked`**
### Example
@ -73,12 +73,12 @@ export component Example inherits Window {
### Properties
* **`text`** (*string*): The text written next to the checkbox.
* **`checked`**: (*bool*): Whether the checkbox is checked or not.
- **`text`** (_string_): The text written next to the checkbox.
- **`checked`**: (_bool_): Whether the checkbox is checked or not.
### Callbacks
* **`toggled`**: The checkbox value changed
- **`toggled`**: The checkbox value changed
### Example
@ -99,9 +99,9 @@ export component Example inherits Window {
### Properties
* **`value`** (*int*): The value.
* **`minimum`** (*int*): The minimum value (default: 0).
* **`maximum`** (*int*): The maximum value (default: 100).
- **`value`** (_int_): The value.
- **`minimum`** (_int_): The minimum value (default: 0).
- **`maximum`** (_int_): The maximum value (default: 100).
### Example
@ -122,13 +122,13 @@ export component Example inherits Window {
### Properties
* **`value`** (*float*): The value.
* **`minimum`** (*float*): The minimum value (default: 0)
* **`maximum`** (*float*): The maximum value (default: 100)
- **`value`** (_float_): The value.
- **`minimum`** (_float_): The minimum value (default: 0)
- **`maximum`** (_float_): The maximum value (default: 100)
### Callbacks
* **`changed(float)`**: The value was changed
- **`changed(float)`**: The value was changed
### Example
@ -149,7 +149,7 @@ export component Example inherits Window {
### Properties
* **`title`** (*string*): A text written as the title of the group box.
- **`title`** (_string_): A text written as the title of the group box.
### Example
@ -174,20 +174,20 @@ A widget used to enter a single line of text
### Properties
* **`text`** (*string*): The text being edited
* **`font-size`** (*length*): the size of the font of the input text
* **`has-focus`**: (*bool*): Set to true when the line edit currently has the focus
* **`placeholder-text`**: (*string*): A placeholder text being shown when there is no text in the edit field
* **`enabled`**: (*bool*): Defaults to true. When false, nothing can be entered
* **`read-only`** (*bool*): When set to `true`, text editing via keyboard and mouse is disabled but
- **`text`** (_string_): The text being edited
- **`font-size`** (_length_): the size of the font of the input text
- **`has-focus`**: (_bool_): Set to true when the line edit currently has the focus
- **`placeholder-text`**: (_string_): A placeholder text being shown when there is no text in the edit field
- **`enabled`**: (_bool_): Defaults to true. When false, nothing can be entered
- **`read-only`** (_bool_): When set to `true`, text editing via keyboard and mouse is disabled but
selecting text is still enabled as well as editing text programatically (default value: `false`)
* **`input-type`** (*enum [`InputType`](builtin_enums.md#InputType)*): The way to allow special input viewing properties such as password fields (default value: `text`).
* **`horizontal-alignment`** (*enum [`TextHorizontalAlignment`](builtin_enums.md#texthorizontalalignment)*): The horizontal alignment of the text.
- **`input-type`** (_enum [`InputType`](builtin_enums.md#InputType)_): The way to allow special input viewing properties such as password fields (default value: `text`).
- **`horizontal-alignment`** (_enum [`TextHorizontalAlignment`](builtin_enums.md#texthorizontalalignment)_): The horizontal alignment of the text.
### Callbacks
* **`accepted`**: Enter was pressed
* **`edited`**: Emitted when the text has changed because the user modified it
- **`accepted`**: Enter was pressed
- **`edited`**: Emitted when the text has changed because the user modified it
### Example
@ -209,23 +209,23 @@ export component Example inherits Window {
Similar to LineEdit, but can be used to enter several lines of text
*Note:* The current implementation only implement very few basic shortcut. More
_Note:_ The current implementation only implement very few basic shortcut. More
shortcut will be implemented in a future version: <https://github.com/slint-ui/slint/issues/474>
### Properties
* **`text`** (*string*): The text being edited
* **`font-size`** (*length*): the size of the font of the input text
* **`has-focus`**: (*bool*): Set to true when the widget currently has the focus
* **`enabled`**: (*bool*): Defaults to true. When false, nothing can be entered
* **`read-only`** (*bool*): When set to `true`, text editing via keyboard and mouse is disabled but
selecting text is still enabled as well as editing text programatically (default value: `false`)
* **`wrap`** (*enum [`TextWrap`](builtin_enums.md#textwrap)*): The way the text wraps (default: word-wrap).
* **`horizontal-alignment`** (*enum [`TextHorizontalAlignment`](builtin_enums.md#texthorizontalalignment)*): The horizontal alignment of the text.
- **`text`** (_string_): The text being edited
- **`font-size`** (_length_): the size of the font of the input text
- **`has-focus`**: (_bool_): Set to true when the widget currently has the focus
- **`enabled`**: (_bool_): Defaults to true. When false, nothing can be entered
- **`read-only`** (_bool_): When set to `true`, text editing via keyboard and mouse is disabled but
selecting text is still enabled as well as editing text programatically (default value: `false`)
- **`wrap`** (_enum [`TextWrap`](builtin_enums.md#textwrap)_): The way the text wraps (default: word-wrap).
- **`horizontal-alignment`** (_enum [`TextHorizontalAlignment`](builtin_enums.md#texthorizontalalignment)_): The horizontal alignment of the text.
### Callbacks
* **`edited`**: Emitted when the text has changed because the user modified it
- **`edited`**: Emitted when the text has changed because the user modified it
### Example
@ -243,7 +243,6 @@ export component Example inherits Window {
}
```
## `ScrollView`
A Scrollview contains a viewport that is bigger than the view and can be
@ -257,11 +256,11 @@ using for loops may be added in the future and is tracked in issue #407.
### Properties
* **`viewport-width`** and **`viewport-height`** (*length*): The `width` and `length` properties of the viewport
* **`viewport-x`** and **`viewport-y`** (*length*): The `x` and `y` properties of the viewport. Usually these are negative
* **`visible-width`** and **`visible-height`** (*length*): The size of the visible area of the ScrollView (not including the scrollbar)
* **`enabled`** and **`has-focus`** (*bool*): property that are only used to render the frame as disabled or focused, but do not
change the behavior of the widget.
- **`viewport-width`** and **`viewport-height`** (_length_): The `width` and `length` properties of the viewport
- **`viewport-x`** and **`viewport-y`** (_length_): The `x` and `y` properties of the viewport. Usually these are negative
- **`visible-width`** and **`visible-height`** (_length_): The size of the visible area of the ScrollView (not including the scrollbar)
- **`enabled`** and **`has-focus`** (_bool_): property that are only used to render the frame as disabled or focused, but do not
change the behavior of the widget.
### Example
@ -337,8 +336,8 @@ The `StandardListViewItem` is equivalent to `{ text: string }` but will be impro
Same as ListView, and in addition:
* **`model`** (*`[StandardListViewItem]`*): The model
* **`current-item`** (*int*): The index of the currently active item. -1 mean none is selected, which is the default
- **`model`** (_`[StandardListViewItem]`_): The model
- **`current-item`** (_int_): The index of the currently active item. -1 mean none is selected, which is the default
### Example
@ -366,14 +365,14 @@ The `StandardTableView` represents a table of data with columns and rows. Cells
Same as ListView, and in addition:
* **`current-sort-column`** (*int*): Indicates the sorted column. -1 mean no column is sorted.
* **`columns`** (*`[TableColumn]`*): Defines the model of the table columns.
* **`rows`** (*`[StandardListViewItem]`*): Defines the model of table rows.
- **`current-sort-column`** (_int_): Indicates the sorted column. -1 mean no column is sorted.
- **`columns`** (_`[TableColumn]`_): Defines the model of the table columns.
- **`rows`** (_`[StandardListViewItem]`_): Defines the model of table rows.
### Callbacks
* **`sort-ascending(int)`**: Emitted if the model should be sorted by the given column in ascending order.
* **`sort-descending(int)`**: Emitted if the model should be sorted by the given column in descending order.
- **`sort-ascending(int)`**: Emitted if the model should be sorted by the given column in ascending order.
- **`sort-descending(int)`**: Emitted if the model should be sorted by the given column in descending order.
### Example
@ -410,14 +409,14 @@ A button that, when clicked, opens a popup to select a value.
### Properties
* **`model`** (*\[string\]*): The list of possible values
* **`current-index`**: (*int*): The index of the selected value (-1 if no value is selected)
* **`current-value`**: (*string*): The currently selected text
* **`enabled`**: (*bool*): When false, the combobox cannot be opened (default: true)
- **`model`** (_\[string\]_): The list of possible values
- **`current-index`**: (_int_): The index of the selected value (-1 if no value is selected)
- **`current-value`**: (_string_): The currently selected text
- **`enabled`**: (_bool_): When false, the combobox cannot be opened (default: true)
### Callbacks
* **`selected(string)`**: A value was selected from the combo box. The argument is the currently selected value.
- **`selected(string)`**: A value was selected from the combo box. The argument is the currently selected value.
### Example
@ -443,11 +442,11 @@ a time.
### Properties
* **`current-index`** (*int*): The index of the currently visible tab
- **`current-index`** (_int_): The index of the currently visible tab
### Properties of the `Tab` element
* **`title`** (*string*): The text written in the tab bar.
- **`title`** (_string_): The text written in the tab bar.
### Example
@ -469,12 +468,10 @@ export component Example inherits Window {
}
```
## `HorizontalBox`, `VerticalBox`, `GridBox`
That's the same as `HorizontalLayout`, `VerticalLayout` or `GridLayout` but the spacing and padding values
depending on the style instead of defaulting to 0.
depending on the style instead of defaulting to 0.
## `AboutSlint`
@ -505,7 +502,6 @@ to one of the style names, such as `fluent` for example.
Select the style with the [`slint_build::compile_with_config()`](https://docs.rs/slint-build/newest/slint_build/fn.compile_with_config.html) function in the compiler configuration argument.
### Selecting the Widget Style When Using the `slint_interpreter` Crate
Select the style with the [`slint_interpreter::ComponentCompiler::set_style()`](https://docs.rs/slint-interpreter/newest/slint_interpreter/struct.ComponentCompiler.html#method.set_style) function.
@ -535,8 +531,8 @@ slint-viewer --style material /path/to/design.slint
Select the style by first opening the Visual Studio Code settings editor:
* On Windows/Linux - File > Preferences > Settings
* On macOS - Code > Preferences > Settings
- On Windows/Linux - File > Preferences > Settings
- On macOS - Code > Preferences > Settings
Then enter the style name under Extensions > Slint > Preview:Style
@ -544,25 +540,3 @@ Then enter the style name under Extensions > Slint > Preview:Style
Select the style by setting the `SLINT_STYLE` environment variable before launching the process.
Alternatively, if your IDE integration allows passing command line parameters, you can specify the style via `--style`.
## structs
### `TableColumn`
`TableColumn` is used to define the column and the column header of a TableView.
### Properties
* **`title`** (*string*): Describes the column header title.
* **`min-width`** (*length*): Defines the minimum with of the column.
* **`width`** (*length*): The current width of the column.
* **`horizontal-stretch`** (*float*): Defines the horizontal stretch of the column.
* **`sort-order`** (*`SortOrder`*): Describes the sort order of the column.
### `StandardListViewItem`
The `StandardListViewItem` is used to display items in the `StandardListView` and the `StandardTableView`.
### Properties
* **`text`** (*string*): Describes the text of the item.

2
xtask/src/license_headers_check.rs
View file

@ -273,6 +273,8 @@ lazy_static! {
("^\\.reuse/dep5$", LicenseLocation::NoLicense), // .reuse files have no license headers
("^api/cpp/docs/Pipfile$", LicenseLocation::NoLicense),
("^api/cpp/docs/conf.py$", LicenseLocation::NoLicense),
("^docs/langref/Pipfile$", LicenseLocation::NoLicense),
("^docs/langref/conf.py$", LicenseLocation::NoLicense),
("^editors/tree-sitter-slint/binding.gyp$", LicenseLocation::NoLicense), // liberal license
("^Cargo.lock$", LicenseLocation::NoLicense),

10
xtask/src/main.rs
View file

@ -11,6 +11,7 @@ mod enumdocs;
mod license_headers_check;
mod nodepackage;
mod reuse_compliance_check;
mod slintdocs;
#[derive(Debug, clap::Parser)]
#[command(author, version, about, long_about = None)]
@ -25,6 +26,8 @@ pub enum TaskCommand {
ReuseComplianceCheck(reuse_compliance_check::ReuseComplianceCheck),
#[command(name = "enumdocs")]
EnumDocs,
#[command(name = "slintdocs")]
SlintDocs(SlintDocsCommand),
}
#[derive(Debug, clap::Parser)]
@ -40,6 +43,12 @@ pub struct CppDocsCommand {
show_warnings: bool,
}
#[derive(Debug, clap::Parser)]
pub struct SlintDocsCommand {
#[arg(long, action)]
show_warnings: bool,
}
/// The root dir of the git repository
fn root_dir() -> PathBuf {
let mut root = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
@ -86,6 +95,7 @@ fn main() -> Result<(), Box<dyn Error>> {
match ApplicationArguments::parse().command {
TaskCommand::CheckLicenseHeaders(cmd) => cmd.check_license_headers()?,
TaskCommand::CppDocs(cmd) => cppdocs::generate(cmd.show_warnings)?,
TaskCommand::SlintDocs(cmd) => slintdocs::generate(cmd.show_warnings)?,
TaskCommand::NodePackage => nodepackage::generate()?,
TaskCommand::ReuseComplianceCheck(cmd) => cmd.check_reuse_compliance()?,
TaskCommand::EnumDocs => enumdocs::generate()?,

104
xtask/src/slintdocs.rs Normal file
View file

@ -0,0 +1,104 @@
// Copyright © SixtyFPS GmbH <info@slint-ui.com>
// SPDX-License-Identifier: GPL-3.0-only OR LicenseRef-Slint-commercial
// cspell:ignore slintdocs pipenv pipfile
use anyhow::{Context, Result};
use std::ffi::OsString;
use std::path::{Path, PathBuf};
fn symlink_file<P: AsRef<Path>, Q: AsRef<Path>>(src: P, dst: Q) -> Result<()> {
if dst.as_ref().exists() {
std::fs::remove_file(dst.as_ref()).context("Error removing old symlink")?;
}
#[cfg(target_os = "windows")]
return std::os::windows::fs::symlink_file(&src, &dst).context("Error creating symlink");
#[cfg(not(target_os = "windows"))]
return std::os::unix::fs::symlink(&src, &dst).context(format!(
"Error creating symlink from {} to {}",
src.as_ref().display(),
dst.as_ref().display()
));
}
fn symlink_dir<P: AsRef<Path>, Q: AsRef<Path>>(src: P, dst: Q) -> Result<()> {
if dst.as_ref().exists() {
std::fs::remove_dir_all(dst.as_ref()).context("Error removing old symlink")?;
}
#[cfg(target_os = "windows")]
return std::os::windows::fs::symlink_dir(&src, &dst).context("Error creating symlink");
#[cfg(not(target_os = "windows"))]
return std::os::unix::fs::symlink(&src, &dst).context(format!(
"Error creating symlink from {} to {}",
src.as_ref().display(),
dst.as_ref().display()
));
}
fn symlink_files_in_dir<S: AsRef<Path>, T: AsRef<Path>, TS: AsRef<Path>>(
src: S,
target: T,
target_to_source: TS,
) -> Result<()> {
for entry in std::fs::read_dir(src.as_ref()).context("Error reading docs source directory")? {
let entry = entry.context("Error reading directory entry")?;
let path = entry.path();
let file_name = path.file_name().unwrap();
let symlink_source = target_to_source.as_ref().to_path_buf().join(&file_name);
let symlink_target = target.as_ref().to_path_buf().join(path.file_name().unwrap());
if path.is_file() {
symlink_file(symlink_source, symlink_target).context("Could not symlink file")?;
} else if path.is_dir() {
symlink_dir(symlink_source, symlink_target).context("Could not symlink directory")?;
}
}
Ok(())
}
pub fn generate(show_warnings: bool) -> Result<(), Box<dyn std::error::Error>> {
let root = super::root_dir();
let docs_source_dir = root.join("docs/langref");
let docs_build_dir = root.join("target/slintdocs");
let html_static_dir = docs_build_dir.join("_static");
std::fs::create_dir_all(docs_build_dir.as_path()).context("Error creating docs build dir")?;
std::fs::create_dir_all(html_static_dir.as_path())
.context("Error creating _static path for docs build")?;
symlink_files_in_dir(
&docs_source_dir,
&docs_build_dir,
["..", "..", "docs", "langref"].iter().collect::<PathBuf>(),
)
.context(format!("Error creating symlinks from docs source {docs_source_dir:?} to docs build dir {docs_build_dir:?}"))?;
let pip_env = vec![(OsString::from("PIPENV_PIPFILE"), docs_source_dir.join("Pipfile"))];
println!("Running pipenv install");
super::run_command("pipenv", &["install"], pip_env.clone())
.context("Error running pipenv install")?;
println!("Running sphinx-build");
let output = super::run_command(
"pipenv",
&[
"run",
"sphinx-build",
docs_build_dir.to_str().unwrap(),
docs_build_dir.join("html").to_str().unwrap(),
],
pip_env,
)
.context("Error running pipenv install")?;
println!("{}", String::from_utf8_lossy(&output.stdout));
if show_warnings {
println!("{}", String::from_utf8_lossy(&output.stderr));
}
Ok(())
}