language-servers/slint
1
0
Fork 0
mirror of https://github.com/slint-ui/slint.git synced 2025-09-28 21:04:47 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

Move widgets out of builtins/ and into its own section under the language reference

Browse source
This commit is contained in:
Simon Hausmann 2023-08-15 11:29:54 +02:00 • committed by Simon Hausmann
parent 2f66331b2b
commit d61a929e34
27 changed files with 649 additions and 632 deletions
Download patch file Download diff file Expand all files Collapse all files

1
docs/reference/index.rst
View file

@ -19,6 +19,7 @@
src/language/concepts/index.rst
src/language/syntax/index.rst
src/language/builtins/index.rst
src/language/widgets/index.rst
.. toctree::
:hidden:

4
docs/reference/src/language/builtins/elements.md
View file

@ -125,7 +125,7 @@ export component Example inherits Dialog {
## `Flickable`
The `Flickable` is a low-level element that is the base for scrollable
widgets, such as the [`ScrollView`](widgets.md#scrollview). When the `viewport-width` or the
widgets, such as the [`ScrollView`](../widgets/scrollview.md). When the `viewport-width` or the
`viewport-height` is greater than the parent's `width` or `height`
respectively, the element becomes scrollable. Note that the `Flickable`
doesn't create a scrollbar. When unset, the `viewport-width` and `viewport-height` are
@ -666,7 +666,7 @@ and the text itself.
- **`horizontal-alignment`** (_in_ _enum [`TextHorizontalAlignment`](enums.md#texthorizontalalignment)_): The horizontal alignment of the text.
- **`letter-spacing`** (_in_ _length_): The letter spacing allows changing the spacing between the glyphs. A positive value increases the spacing and a negative value decreases the distance. (default value: 0)
- **`overflow`** (_in_ _enum [`TextOverflow`](enums.md#textoverflow)_): What happens when the text overflows (default value: clip).
- **`text`** (_in_ _[string](../reference/types.md#strings)_): The text rendered.
- **`text`** (_in_ _[string](../syntax/types.md#strings)_): The text rendered.
- **`vertical-alignment`** (_in_ _enum [`TextVerticalAlignment`](enums.md#textverticalalignment)_): The vertical alignment of the text.
- **`wrap`** (_in_ _enum [`TextWrap`](enums.md#textwrap)_): The way the text wraps (default value: `no-wrap`).

1
docs/reference/src/language/builtins/index.rst
View file

@ -16,4 +16,3 @@ Builtins
globals.md
namespaces.md
structs.md
widgets.md

619
docs/reference/src/language/builtins/widgets.md
View file

@ -1,619 +0,0 @@
# Widgets
Slint provides a series of built-in widgets that can be imported from `"std-widgets.slint"`.
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.
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` isn't available, `fluent` is the default.
All widgets support all [properties common to builtin elements](elements.md#common-properties).
## `AboutSlint`
This element displays a "Made with Slint" badge.
```slint
import { AboutSlint } from "std-widgets.slint";
export component Example inherits Window {
height: 175px;
AboutSlint {
}
}
```
## `Button`
A simple button. Common types of buttons can also be created with [`StandardButton`](#standardbutton).
### Properties
- **`checkable`** (_in_ _bool_): Shows whether the button can be checked or not. This enables the `checked` property to possibly become true.
- **`checked`** (_inout_ _bool_): Shows whether the button is checked or not. Needs `checkable` to be true to work.
- **`enabled`**: (_in_ _bool_): Defaults to true. When false, the button cannot be pressed
- **`has-focus`**: (_out_ _bool_): Set to true when the button has keyboard focus.
- **`icon`** (_in_ _image_): The image to show in the button. Note that not all styles support drawing icons.
- **`pressed`**: (_out_ _bool_): Set to true when the button is pressed.
- **`text`** (_in_ _string_): The text written in the button.
- **`primary`** (_in_ _bool_): If set to true the button is displayed with the primary accent color (default: false).
### Callbacks
- **`clicked()`**
### Example
```slint
import { Button, VerticalBox } from "std-widgets.slint";
export component Example inherits Window {
VerticalBox {
Button {
text: "Click Me";
clicked => { self.text = "Clicked"; }
}
}
}
```
## `CheckBox`
Use a `CheckBox` to let the user select or deselect values, for example in a list with multiple options. Consider using a `Switch` element instead if the action resembles more something that's turned on or off.
### Properties
- **`checked`**: (_inout_ _bool_): Whether the checkbox is checked or not (default: false).
- **`enabled`**: (_in_ _bool_): Defaults to true. When false, the checkbox can't be pressed (default: true)
- **`has-focus`**: (_out_ _bool_): Set to true when the checkbox has keyboard focus (default: false).
- **`text`** (_in_ _string_): The text written next to the checkbox.
### Callbacks
- **`toggled()`**: The checkbox value changed
### Example
```slint
import { CheckBox } from "std-widgets.slint";
export component Example inherits Window {
width: 200px;
height: 25px;
CheckBox {
width: parent.width;
height: parent.height;
text: "Hello World";
}
}
```
## `ComboBox`
A button that, when clicked, opens a popup to select a value.
### Properties
- **`current-index`**: (_in-out_ _int_): The index of the selected value (-1 if no value is selected)
- **`current-value`**: (_in-out_ _string_): The currently selected text
- **`enabled`**: (_in_ _bool_): Defaults to true. When false, the combobox can't be interacted with
- **`has-focus`**: (_out_ _bool_): Set to true when the combobox has keyboard focus.
- **`model`** (_in_ _\[string\]_): The list of possible values
### Callbacks
- **`selected(`_`string`_`)`**: A value was selected from the combo box. The argument is the currently selected value.
### Example
```slint
import { ComboBox } from "std-widgets.slint";
export component Example inherits Window {
width: 200px;
height: 130px;
ComboBox {
y: 0px;
width: self.preferred-width;
height: self.preferred-height;
model: ["first", "second", "third"];
current-value: "first";
}
}
```
## `GridBox`
A `GridBox` is a [`GridLayout`](elements.md#gridlayout) where the spacing and padding values
depend on the style instead of defaulting to 0.
## `GroupBox`
A `GroupBox` is a container that groups its children together under a common title.
### Properties
- **`enabled`**: (_in_ _bool_): Defaults to true. When false, the groupbox can't be interacted with
- **`title`** (_in_ _string_): A text written as the title of the group box.
### Example
```slint
import { GroupBox , VerticalBox, CheckBox } from "std-widgets.slint";
export component Example inherits Window {
width: 200px;
height: 100px;
GroupBox {
title: "Groceries";
VerticalLayout {
CheckBox { text: "Bread"; checked: true ;}
CheckBox { text: "Fruits"; }
}
}
}
```
## `HorizontalBox`
A `HorizontalBox` is a [`HorizontalLayout`](elements.md#verticallayout-and-horizontallayout) where the spacing and padding values
depend on the style instead of defaulting to 0.
## `LineEdit`
A widget used to enter a single line of text. See [`TextEdit`](#textedit) for
a widget able to handle several lines of text.
### Properties
- **`enabled`**: (_in_ _bool_): Defaults to true. When false, nothing can be entered selecting text is still enabled as well as editing text programmatically (default value: `false`)
- **`font-size`** (_in_ _length_): the size of the font of the input text
- **`has-focus`**: (_out_ _bool_): Set to true when the line edit currently has the focus
- **`horizontal-alignment`** (_in_ _enum [`TextHorizontalAlignment`](enums.md#texthorizontalalignment)_): The horizontal alignment of the text.
- **`input-type`** (_in_ _enum [`InputType`](enums.md#inputtype)_): The way to allow special input viewing properties such as password fields (default value: `text`).
- **`placeholder-text`**: (_in_ _string_): A placeholder text being shown when there is no text in the edit field
- **`read-only`** (_in_ _bool_): When set to true, text editing via keyboard and mouse is disabled but
- **`text`** (_in-out_ _string_): The text being edited
### Functions
- **`focus()`** Call this function to focus the LineEdit and make it receive future keyboard events.
- **`select-all()`** Selects all text.
- **`clear-selection()`** Clears the selection.
- **`copy()`** Copies the selected text to the clipboard.
- **`cut()`** Copies the selected text to the clipboard and removes it from the editable area.
- **`paste()`** Pastes the text content of the clipboard at the cursor position.
### Callbacks
- **`accepted(`_`string`_`)`**: Enter was pressed
- **`edited(`_`string`_`)`**: Emitted when the text has changed because the user modified it
### Example
```slint
import { LineEdit } from "std-widgets.slint";
export component Example inherits Window {
width: 200px;
height: 25px;
LineEdit {
font-size: 14px;
width: parent.width;
height: parent.height;
placeholder-text: "Enter text here";
}
}
```
## `ListView`
A ListView is like a Scrollview but it should have a `for` element, and the content are
automatically laid out in a list.
Elements are only instantiated if they are visible
### Properties
Same as [`ScrollView`](#scrollview)
### Example
```slint
import { ListView } from "std-widgets.slint";
export component Example inherits Window {
width: 150px;
height: 150px;
ListView {
width: 150px;
height: 150px;
for data in [
{ text: "Blue", color: #0000ff, bg: #eeeeee},
{ text: "Red", color: #ff0000, bg: #eeeeee},
{ text: "Green", color: #00ff00, bg: #eeeeee},
{ text: "Yellow", color: #ffff00, bg: #222222 },
{ text: "Black", color: #000000, bg: #eeeeee },
{ text: "White", color: #ffffff, bg: #222222 },
{ text: "Magenta", color: #ff00ff, bg: #eeeeee },
{ text: "Cyan", color: #00ffff, bg: #222222 },
] : Rectangle {
height: 30px;
background: data.bg;
width: parent.width;
Text {
x: 0;
text: data.text;
color: data.color;
}
}
}
}
```
## `ProgressIndicator`
The `ProgressIndicator` informs the user about the status of an on-going operation, such as loading data from the network.
### Properties
- **`indeterminate`**: (_in_ _bool_): Set to true if the progress of the operation cannot be determined by value (default value: `false`).
- **`progress`** (_in_ _float_): Percentage of completion, as value between 0 and 1. Values less than 0 or greater than 1 are capped.
### Example
```slint
import { ProgressIndicator } from "std-widgets.slint";
export component Example inherits Window {
width: 200px;
height: 25px;
ProgressIndicator {
width: parent.width;
height: parent.height;
progress: 50%;
}
}
```
## `ScrollView`
A Scrollview contains a viewport that is bigger than the view and can be
scrolled. It has scrollbar to interact with. The viewport-width and
viewport-height are calculated automatically to create a scollable view
except for when using a for loop to populate the elements. In that case
the viewport-width and viewport-height aren't calculated automatically
and must be set manually for scrolling to work. The ability to
automatically calculate the viewport-width and viewport-height when
using for loops may be added in the future and is tracked in issue #407.
### Properties
- **`enabled`** (_in_ _bool_): Used to render the frame as disabled or enabled, but doesn't change behavior of the widget.
- **`has-focus`** (_in-out_ _bool_): Used to render the frame as focused or unfocused, but doesn't change the behavior of the widget.
- **`viewport-width`** and **`viewport-height`** (_in-out_ _length_): The `width` and `length` properties of the viewport
- **`viewport-x`** and **`viewport-y`** (_in-out_ _length_): The `x` and `y` properties of the viewport. Usually these are negative
- **`visible-width`** and **`visible-height`** (_out_ _length_): The size of the visible area of the ScrollView (not including the scrollbar)
### Example
```slint
import { ScrollView } from "std-widgets.slint";
export component Example inherits Window {
width: 200px;
height: 200px;
ScrollView {
width: 200px;
height: 200px;
viewport-width: 300px;
viewport-height: 300px;
Rectangle { width: 30px; height: 30px; x: 275px; y: 50px; background: blue; }
Rectangle { width: 30px; height: 30px; x: 175px; y: 130px; background: red; }
Rectangle { width: 30px; height: 30px; x: 25px; y: 210px; background: yellow; }
Rectangle { width: 30px; height: 30px; x: 98px; y: 55px; background: orange; }
}
}
```
## `Slider`
### Properties
- **`enabled`**: (_in_ _bool_): Defaults to true. You can't interact with the slider if enabled is false.
- **`has-focus`**: (_out_ _bool_): Set to true when the slider currently has the focus
- **`value`** (_in-out_ _float_): The value.
- **`minimum`** (_in_ _float_): The minimum value (default: 0)
- **`maximum`** (_in_ _float_): The maximum value (default: 100)
### Callbacks
- **`changed(float)`**: The value was changed
### Example
```slint
import { Slider } from "std-widgets.slint";
export component Example inherits Window {
width: 200px;
height: 25px;
Slider {
width: parent.width;
height: parent.height;
value: 42;
}
}
```
## `SpinBox`
### Properties
- **`enabled`**: (_in_ _bool_): Defaults to true. You can't interact with the spinbox if enabled is false.
- **`has-focus`**: (_out_ _bool_): Set to true when the spinbox currently has the focus
- **`value`** (_in-out_ _int_): The value.
- **`minimum`** (_in_ _int_): The minimum value (default: 0).
- **`maximum`** (_in_ _int_): The maximum value (default: 100).
### Callbacks
- **`edited(`_`int`_`)`**: Emitted when the value has changed because the user modified it
### Example
```slint
import { SpinBox } from "std-widgets.slint";
export component Example inherits Window {
width: 200px;
height: 25px;
SpinBox {
width: parent.width;
height: parent.height;
value: 42;
}
}
```
## `StandardButton`
The StandardButton looks like a button, but instead of customizing with `text` and `icon`,
it can used one of the pre-defined `kind` and the text and icon will depend on the style.
### Properties
- **`enabled`**: (_in_ _bool_): Defaults to true. When false, the button can't be pressed
- **`has-focus`**: (_out_ _bool_): Set to true when the button currently has the focus
- **`kind`** (_in_ _enum [`StandardButtonKind`](enums.md#standardbuttonkind)_): The kind of button, one of `ok` `cancel`, `apply`, `close`, `reset`, `help`, `yes`, `no,` `abort`, `retry` or `ignore`
- **`pressed`**: (_out_ _bool_): Set to true when the button is pressed.
### Callbacks
- **`clicked()`**
### Example
```slint
import { StandardButton, VerticalBox } from "std-widgets.slint";
export component Example inherits Window {
VerticalBox {
StandardButton { kind: ok; }
StandardButton { kind: apply; }
StandardButton { kind: cancel; }
}
}
```
## `StandardListView`
Like ListView, but with a default delegate, and a `model` property which is a model of type
[`StandardListViewItem`](structs.md#standardlistviewitem).
### Properties
Same as [`ListView`](#listview), and in addition:
- **`current-item`** (_in-out_ _int_): The index of the currently active item. -1 mean none is selected, which is the default
- **`model`** (_in_ _[`StandardListViewItem`](structs.md#standardlistviewitem)_): The model
### Functions
- **`set-current-item(_index: int_)`**: Sets the current item and brings it into view
### Callbacks
- **`current-item-changed(`_`int`_`)`**: Emitted when the current item has changed because the user modified it
- **`item-pointer-event(`_`index: int`_`, `_`event: PointerEvent`_`, `_`pos: Point`_`)`**: Emitted on any mouse pointer event similar to `TouchArea`. Arguments are item index associated with the event, the `PointerEvent` itself and the mouse position within the listview.
### Example
```slint
import { StandardListView } from "std-widgets.slint";
export component Example inherits Window {
width: 150px;
height: 150px;
StandardListView {
width: 150px;
height: 150px;
model: [ { text: "Blue"}, { text: "Red" }, { text: "Green" },
{ text: "Yellow" }, { text: "Black"}, { text: "White"},
{ text: "Magenta" }, { text: "Cyan" },
];
}
}
```
## `StandardTableView`
The `StandardTableView` represents a table of data with columns and rows. Cells
are organised in a model where each row is a model of
\[[`StandardListViewItem`](structs.md#standardlistviewitem)\].
### Properties
Same as [`ListView`](#listview), and in addition:
- **`current-sort-column`** (_out_ _int_): Indicates the sorted column. -1 mean no column is sorted.
- **`columns`** (_in-out_ _\[[`TableColumn`](structs.md#tablecolumn)\]_): Defines the model of the table columns.
- **`rows`** (_\[\[[`StandardListViewItem`](structs.md#standardlistviewitem)\]\]_): Defines the model of table rows.
- **`current-row`** (_in-out_ _int_): The index of the currently active row. -1 mean none is selected, which is the default.
### 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.
- **`row-pointer-event(`_`index: int`_`, `_`event: PointerEvent`_`, `_`pos: Point`_`)`**: Emitted on any mouse pointer event similar to `TouchArea`. Arguments are row index associated with the event, the `PointerEvent` itself and the mouse position within the tableview.
- **`current-row-changed(`_`int`_`)`**: Emitted when the current row has changed because the user modified it
### Functions
- **`set-current-row(index: int)`: Sets the current row and brings it into view
### Example
```slint
import { StandardTableView } from "std-widgets.slint";
export component Example inherits Window {
width: 230px;
height: 200px;
StandardTableView {
width: 230px;
height: 200px;
columns: [
{ title: "Header 1" },
{ title: "Header 2" },
];
rows: [
[
{ text: "Item 1" }, { text: "Item 2" },
],
[
{ text: "Item 1" }, { text: "Item 2" },
],
[
{ text: "Item 1" }, { text: "Item 2" },
]
];
}
}
```
## `Switch`
A `Switch` is a representation of a physical switch that allows users to turn things on or off. Consider using a `CheckBox` instead if you want the user to select or deselect values, for example in a list with multiple options.
### Properties
- **`checked`**: (_inout_ _bool_): Whether the switch is checked or not (default: false).
- **`enabled`**: (_in_ _bool_): Defaults to true. When false, the switch can't be pressed (default: true).
- **`has-focus`**: (_out_ _bool_): Set to true when the switch has keyboard focue (default: false).
- **`text`** (_in_ _string_): The text written next to the switch.
### Callbacks
- **`toggled()`**: The switch value changed
### Example
```slint
import { Switch } from "std-widgets.slint";
export component Example inherits Window {
width: 200px;
height: 25px;
Switch {
width: parent.width;
height: parent.height;
text: "Hello World";
}
}
```
## `TabWidget`
`TabWidget` is a container for a set of tabs. It can only have `Tab` elements as children and only one tab will be visible at
a time.
### Properties
- **`content-min-width`** and **`content-min-height`** (_out_ _length_): The minimum width and height of the contents
- **`content-width`** and **`content-height`** (_out_ _length_): The width and height of the contents
- **`content-x`** and **`content-y`** (_out_ _length_): The x and y position of the contents
- **`current-focused`** (_in_ _int_): The index of the tab that has focus. This tab may or may not be visible.
- **`current-index`** (_in_ _int_): The index of the currently visible tab
- **`tabbar-preferred-width`** and **`tabbar-preferred-height`** (_in_ _length_): The preferred width and height of the tab bar
- **`tabbar-width`** and **`tabbar-height`** (_out_ _length_): The width and height of the tab bar
- **`tabbar-x`** and **`tabbar-y`** (_out_ _length_): The x and y position of the tab bar
### Properties of the `Tab` element
- **`current-focused`** (_out_ _int_): The index of this tab that has focus at this time or -1 if none is focused
- **`enabled`**: (_in_ _bool_): Defaults to true. When false, the tab can't be activated
- **`icon`** (_in_ _image_): The image on the tab
- **`num-tabs`** (_out_ _int_): The number of tabs in the current `TabBar`
- **`tab-index`** (_out_ _int_): The index of this tab
- **`title`** (_in_ _string_): The text written on the tab
### Example
```slint
import { TabWidget } from "std-widgets.slint";
export component Example inherits Window {
width: 200px;
height: 200px;
TabWidget {
Tab {
title: "First";
Rectangle { background: orange; }
}
Tab {
title: "Second";
Rectangle { background: pink; }
}
}
}
```
## `TextEdit`
Similar to [`LineEdit`](#lineedit)`, but can be used to enter several lines of text
_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
- **`font-size`** (_in_ _length_): the size of the font of the input text
- **`text`** (_in-out_ _string_): The text being edited
- **`has-focus`**: (_in_out_ _bool_): Set to true when the widget currently has the focus
- **`enabled`**: (_in_ _bool_): Defaults to true. When false, nothing can be entered
- **`read-only`** (_in_ _bool_): When set to true, text editing via keyboard and mouse is disabled but selecting text is still enabled as well as editing text programmatically (default value: `false`)
- **`wrap`** (_in_ _enum [`TextWrap`](enums.md#textwrap)_): The way the text wraps (default: word-wrap).
- **`horizontal-alignment`** (_in_ _enum [`TextHorizontalAlignment`](enums.md#texthorizontalalignment)_): The horizontal alignment of the text.
### Functions
- **`focus()`** Call this function to focus the TextEdit and make it receive future keyboard events.
- **`select-all()`** Selects all text.
- **`clear-selection()`** Clears the selection.
- **`copy()`** Copies the selected text to the clipboard.
- **`cut()`** Copies the selected text to the clipboard and removes it from the editable area.
- **`paste()`** Pastes the text content of the clipboard at the cursor position.
### Callbacks
- **`edited(`_`string`_`)`**: Emitted when the text has changed because the user modified it
### Example
```slint
import { TextEdit } from "std-widgets.slint";
export component Example inherits Window {
width: 200px;
height: 200px;
TextEdit {
font-size: 14px;
width: parent.width;
height: parent.height;
text: "Lorem ipsum dolor sit amet,\n consectetur adipisici elit";
}
}
```
## `VerticalBox`
A `VerticalBox` is a [`VerticalLayout`](elements.md#verticallayout-and-horizontallayout) where the spacing and padding values
depend on the style instead of defaulting to 0.

2
docs/reference/src/language/concepts/file.md
View file

@ -68,7 +68,7 @@ export component MyApp inherits Window {
}
```
Names have to be valid [identifiers](../reference/identifiers.md).
Names have to be valid [identifiers](../syntax/identifiers.md).
Some elements are also accessible under pre-defined names:

12
docs/reference/src/language/widgets/aboutslint.md Normal file
View file

@ -0,0 +1,12 @@
## `AboutSlint`
This element displays a "Made with Slint" badge.
```slint
import { AboutSlint } from "std-widgets.slint";
export component Example inherits Window {
height: 175px;
AboutSlint {
}
}
```

33
docs/reference/src/language/widgets/button.md Normal file
View file

@ -0,0 +1,33 @@
## `Button`
A simple button. Common types of buttons can also be created with [`StandardButton`](#standardbutton).
### Properties
- **`checkable`** (_in_ _bool_): Shows whether the button can be checked or not. This enables the `checked` property to possibly become true.
- **`checked`** (_inout_ _bool_): Shows whether the button is checked or not. Needs `checkable` to be true to work.
- **`enabled`**: (_in_ _bool_): Defaults to true. When false, the button cannot be pressed
- **`has-focus`**: (_out_ _bool_): Set to true when the button has keyboard focus.
- **`icon`** (_in_ _image_): The image to show in the button. Note that not all styles support drawing icons.
- **`pressed`**: (_out_ _bool_): Set to true when the button is pressed.
- **`text`** (_in_ _string_): The text written in the button.
- **`primary`** (_in_ _bool_): If set to true the button is displayed with the primary accent color (default: false).
### Callbacks
- **`clicked()`**
### Example
```slint
import { Button, VerticalBox } from "std-widgets.slint";
export component Example inherits Window {
VerticalBox {
Button {
text: "Click Me";
clicked => { self.text = "Clicked"; }
}
}
}
```

30
docs/reference/src/language/widgets/checkbox.md Normal file
View file

@ -0,0 +1,30 @@
## `CheckBox`
Use a `CheckBox` to let the user select or deselect values, for example in a list with multiple options. Consider using a `Switch` element instead if the action resembles more something that's turned on or off.
### Properties
- **`checked`**: (_inout_ _bool_): Whether the checkbox is checked or not (default: false).
- **`enabled`**: (_in_ _bool_): Defaults to true. When false, the checkbox can't be pressed (default: true)
- **`has-focus`**: (_out_ _bool_): Set to true when the checkbox has keyboard focus (default: false).
- **`text`** (_in_ _string_): The text written next to the checkbox.
### Callbacks
- **`toggled()`**: The checkbox value changed
### Example
```slint
import { CheckBox } from "std-widgets.slint";
export component Example inherits Window {
width: 200px;
height: 25px;
CheckBox {
width: parent.width;
height: parent.height;
text: "Hello World";
}
}
```

33
docs/reference/src/language/widgets/combobox.md Normal file
View file

@ -0,0 +1,33 @@
## `ComboBox`
A button that, when clicked, opens a popup to select a value.
### Properties
- **`current-index`**: (_in-out_ _int_): The index of the selected value (-1 if no value is selected)
- **`current-value`**: (_in-out_ _string_): The currently selected text
- **`enabled`**: (_in_ _bool_): Defaults to true. When false, the combobox can't be interacted with
- **`has-focus`**: (_out_ _bool_): Set to true when the combobox has keyboard focus.
- **`model`** (_in_ _\[string\]_): The list of possible values
### Callbacks
- **`selected(`_`string`_`)`**: A value was selected from the combo box. The argument is the currently selected value.
### Example
```slint
import { ComboBox } from "std-widgets.slint";
export component Example inherits Window {
width: 200px;
height: 130px;
ComboBox {
y: 0px;
width: self.preferred-width;
height: self.preferred-height;
model: ["first", "second", "third"];
current-value: "first";
}
}
```

30
docs/reference/src/language/widgets/gridbox.md Normal file
View file

@ -0,0 +1,30 @@
## `GridBox`
A `GridBox` is a [`GridLayout`](../builtins/elements.md#gridlayout) where the spacing and padding values
depend on the style instead of defaulting to 0.
## `GroupBox`
A `GroupBox` is a container that groups its children together under a common title.
### Properties
- **`enabled`**: (_in_ _bool_): Defaults to true. When false, the groupbox can't be interacted with
- **`title`** (_in_ _string_): A text written as the title of the group box.
### Example
```slint
import { GroupBox , VerticalBox, CheckBox } from "std-widgets.slint";
export component Example inherits Window {
width: 200px;
height: 100px;
GroupBox {
title: "Groceries";
VerticalLayout {
CheckBox { text: "Bread"; checked: true ;}
CheckBox { text: "Fruits"; }
}
}
}
```

4
docs/reference/src/language/widgets/horizontalbox.md Normal file
View file

@ -0,0 +1,4 @@
## `HorizontalBox`
A `HorizontalBox` is a [`HorizontalLayout`](../builtins/elements.md#verticallayout-and-horizontallayout) where the spacing and padding values
depend on the style instead of defaulting to 0.

33
docs/reference/src/language/widgets/index.rst Normal file
View file

@ -0,0 +1,33 @@
.. Copyright © SixtyFPS GmbH <info@slint.dev>
.. SPDX-License-Identifier: MIT
Widgets
========
.. include:: widgets.md
:parser: myst_parser.sphinx_
.. toctree::
:hidden:
:maxdepth: 4
:caption: Widgets
aboutslint.md
button.md
checkbox.md
combobox.md
gridbox.md
horizontalbox.md
lineedit.md
listview.md
progressindicator.md
scrollview.md
slider.md
spinbox.md
standardbutton.md
standardlistview.md
standardtableview.md
switch.md
tabwidget.md
textedit.md
verticalbox.md

45
docs/reference/src/language/widgets/lineedit.md Normal file
View file

@ -0,0 +1,45 @@
## `LineEdit`
A widget used to enter a single line of text. See [`TextEdit`](#textedit) for
a widget able to handle several lines of text.
### Properties
- **`enabled`**: (_in_ _bool_): Defaults to true. When false, nothing can be entered selecting text is still enabled as well as editing text programmatically (default value: `false`)
- **`font-size`** (_in_ _length_): the size of the font of the input text
- **`has-focus`**: (_out_ _bool_): Set to true when the line edit currently has the focus
- **`horizontal-alignment`** (_in_ _enum [`TextHorizontalAlignment`](../builtins/enums.md#texthorizontalalignment)_): The horizontal alignment of the text.
- **`input-type`** (_in_ _enum [`InputType`](../builtins/enums.md#inputtype)_): The way to allow special input viewing properties such as password fields (default value: `text`).
- **`placeholder-text`**: (_in_ _string_): A placeholder text being shown when there is no text in the edit field
- **`read-only`** (_in_ _bool_): When set to true, text editing via keyboard and mouse is disabled but
- **`text`** (_in-out_ _string_): The text being edited
### Functions
- **`focus()`** Call this function to focus the LineEdit and make it receive future keyboard events.
- **`select-all()`** Selects all text.
- **`clear-selection()`** Clears the selection.
- **`copy()`** Copies the selected text to the clipboard.
- **`cut()`** Copies the selected text to the clipboard and removes it from the editable area.
- **`paste()`** Pastes the text content of the clipboard at the cursor position.
### Callbacks
- **`accepted(`_`string`_`)`**: Enter was pressed
- **`edited(`_`string`_`)`**: Emitted when the text has changed because the user modified it
### Example
```slint
import { LineEdit } from "std-widgets.slint";
export component Example inherits Window {
width: 200px;
height: 25px;
LineEdit {
font-size: 14px;
width: parent.width;
height: parent.height;
placeholder-text: "Enter text here";
}
}
```

42
docs/reference/src/language/widgets/listview.md Normal file
View file

@ -0,0 +1,42 @@
## `ListView`
A ListView is like a Scrollview but it should have a `for` element, and the content are
automatically laid out in a list.
Elements are only instantiated if they are visible
### Properties
Same as [`ScrollView`](#scrollview)
### Example
```slint
import { ListView } from "std-widgets.slint";
export component Example inherits Window {
width: 150px;
height: 150px;
ListView {
width: 150px;
height: 150px;
for data in [
{ text: "Blue", color: #0000ff, bg: #eeeeee},
{ text: "Red", color: #ff0000, bg: #eeeeee},
{ text: "Green", color: #00ff00, bg: #eeeeee},
{ text: "Yellow", color: #ffff00, bg: #222222 },
{ text: "Black", color: #000000, bg: #eeeeee },
{ text: "White", color: #ffffff, bg: #222222 },
{ text: "Magenta", color: #ff00ff, bg: #eeeeee },
{ text: "Cyan", color: #00ffff, bg: #222222 },
] : Rectangle {
height: 30px;
background: data.bg;
width: parent.width;
Text {
x: 0;
text: data.text;
color: data.color;
}
}
}
}
```

23
docs/reference/src/language/widgets/progressindicator.md Normal file
View file

@ -0,0 +1,23 @@
## `ProgressIndicator`
The `ProgressIndicator` informs the user about the status of an on-going operation, such as loading data from the network.
### Properties
- **`indeterminate`**: (_in_ _bool_): Set to true if the progress of the operation cannot be determined by value (default value: `false`).
- **`progress`** (_in_ _float_): Percentage of completion, as value between 0 and 1. Values less than 0 or greater than 1 are capped.
### Example
```slint
import { ProgressIndicator } from "std-widgets.slint";
export component Example inherits Window {
width: 200px;
height: 25px;
ProgressIndicator {
width: parent.width;
height: parent.height;
progress: 50%;
}
}
```

38
docs/reference/src/language/widgets/scrollview.md Normal file
View file

@ -0,0 +1,38 @@
## `ScrollView`
A Scrollview contains a viewport that is bigger than the view and can be
scrolled. It has scrollbar to interact with. The viewport-width and
viewport-height are calculated automatically to create a scollable view
except for when using a for loop to populate the elements. In that case
the viewport-width and viewport-height aren't calculated automatically
and must be set manually for scrolling to work. The ability to
automatically calculate the viewport-width and viewport-height when
using for loops may be added in the future and is tracked in issue #407.
### Properties
- **`enabled`** (_in_ _bool_): Used to render the frame as disabled or enabled, but doesn't change behavior of the widget.
- **`has-focus`** (_in-out_ _bool_): Used to render the frame as focused or unfocused, but doesn't change the behavior of the widget.
- **`viewport-width`** and **`viewport-height`** (_in-out_ _length_): The `width` and `length` properties of the viewport
- **`viewport-x`** and **`viewport-y`** (_in-out_ _length_): The `x` and `y` properties of the viewport. Usually these are negative
- **`visible-width`** and **`visible-height`** (_out_ _length_): The size of the visible area of the ScrollView (not including the scrollbar)
### Example
```slint
import { ScrollView } from "std-widgets.slint";
export component Example inherits Window {
width: 200px;
height: 200px;
ScrollView {
width: 200px;
height: 200px;
viewport-width: 300px;
viewport-height: 300px;
Rectangle { width: 30px; height: 30px; x: 275px; y: 50px; background: blue; }
Rectangle { width: 30px; height: 30px; x: 175px; y: 130px; background: red; }
Rectangle { width: 30px; height: 30px; x: 25px; y: 210px; background: yellow; }
Rectangle { width: 30px; height: 30px; x: 98px; y: 55px; background: orange; }
}
}
```

28
docs/reference/src/language/widgets/slider.md Normal file
View file

@ -0,0 +1,28 @@
## `Slider`
### Properties
- **`enabled`**: (_in_ _bool_): Defaults to true. You can't interact with the slider if enabled is false.
- **`has-focus`**: (_out_ _bool_): Set to true when the slider currently has the focus
- **`value`** (_in-out_ _float_): The value.
- **`minimum`** (_in_ _float_): The minimum value (default: 0)
- **`maximum`** (_in_ _float_): The maximum value (default: 100)
### Callbacks
- **`changed(float)`**: The value was changed
### Example
```slint
import { Slider } from "std-widgets.slint";
export component Example inherits Window {
width: 200px;
height: 25px;
Slider {
width: parent.width;
height: parent.height;
value: 42;
}
}
```

28
docs/reference/src/language/widgets/spinbox.md Normal file
View file

@ -0,0 +1,28 @@
## `SpinBox`
### Properties
- **`enabled`**: (_in_ _bool_): Defaults to true. You can't interact with the spinbox if enabled is false.
- **`has-focus`**: (_out_ _bool_): Set to true when the spinbox currently has the focus
- **`value`** (_in-out_ _int_): The value.
- **`minimum`** (_in_ _int_): The minimum value (default: 0).
- **`maximum`** (_in_ _int_): The maximum value (default: 100).
### Callbacks
- **`edited(`_`int`_`)`**: Emitted when the value has changed because the user modified it
### Example
```slint
import { SpinBox } from "std-widgets.slint";
export component Example inherits Window {
width: 200px;
height: 25px;
SpinBox {
width: parent.width;
height: parent.height;
value: 42;
}
}
```

28
docs/reference/src/language/widgets/standardbutton.md Normal file
View file

@ -0,0 +1,28 @@
## `StandardButton`
The StandardButton looks like a button, but instead of customizing with `text` and `icon`,
it can used one of the pre-defined `kind` and the text and icon will depend on the style.
### Properties
- **`enabled`**: (_in_ _bool_): Defaults to true. When false, the button can't be pressed
- **`has-focus`**: (_out_ _bool_): Set to true when the button currently has the focus
- **`kind`** (_in_ _enum [`StandardButtonKind`](../builtins/enums.md#standardbuttonkind)_): The kind of button, one of `ok` `cancel`, `apply`, `close`, `reset`, `help`, `yes`, `no,` `abort`, `retry` or `ignore`
- **`pressed`**: (_out_ _bool_): Set to true when the button is pressed.
### Callbacks
- **`clicked()`**
### Example
```slint
import { StandardButton, VerticalBox } from "std-widgets.slint";
export component Example inherits Window {
VerticalBox {
StandardButton { kind: ok; }
StandardButton { kind: apply; }
StandardButton { kind: cancel; }
}
}
```

38
docs/reference/src/language/widgets/standardlistview.md Normal file
View file

@ -0,0 +1,38 @@
## `StandardListView`
Like ListView, but with a default delegate, and a `model` property which is a model of type
[`StandardListViewItem`](../builtins/structs.md#standardlistviewitem).
### Properties
Same as [`ListView`](#listview), and in addition:
- **`current-item`** (_in-out_ _int_): The index of the currently active item. -1 mean none is selected, which is the default
- **`model`** (_in_ _[`StandardListViewItem`](../builtins/structs.md#standardlistviewitem)_): The model
### Functions
- **`set-current-item(_index: int_)`**: Sets the current item and brings it into view
### Callbacks
- **`current-item-changed(`_`int`_`)`**: Emitted when the current item has changed because the user modified it
- **`item-pointer-event(`_`index: int`_`, `_`event: PointerEvent`_`, `_`pos: Point`_`)`**: Emitted on any mouse pointer event similar to `TouchArea`. Arguments are item index associated with the event, the `PointerEvent` itself and the mouse position within the listview.
### Example
```slint
import { StandardListView } from "std-widgets.slint";
export component Example inherits Window {
width: 150px;
height: 150px;
StandardListView {
width: 150px;
height: 150px;
model: [ { text: "Blue"}, { text: "Red" }, { text: "Green" },
{ text: "Yellow" }, { text: "Black"}, { text: "White"},
{ text: "Magenta" }, { text: "Cyan" },
];
}
}
```

54
docs/reference/src/language/widgets/standardtableview.md Normal file
View file

@ -0,0 +1,54 @@
## `StandardTableView`
The `StandardTableView` represents a table of data with columns and rows. Cells
are organised in a model where each row is a model of
\[[`StandardListViewItem`](../builtins/structs.md#standardlistviewitem)\].
### Properties
Same as [`ListView`](#listview), and in addition:
- **`current-sort-column`** (_out_ _int_): Indicates the sorted column. -1 mean no column is sorted.
- **`columns`** (_in-out_ _\[[`TableColumn`](../builtins/structs.md#tablecolumn)\]_): Defines the model of the table columns.
- **`rows`** (_\[\[[`StandardListViewItem`](../builtins/structs.md#standardlistviewitem)\]\]_): Defines the model of table rows.
- **`current-row`** (_in-out_ _int_): The index of the currently active row. -1 mean none is selected, which is the default.
### 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.
- **`row-pointer-event(`_`index: int`_`, `_`event: PointerEvent`_`, `_`pos: Point`_`)`**: Emitted on any mouse pointer event similar to `TouchArea`. Arguments are row index associated with the event, the `PointerEvent` itself and the mouse position within the tableview.
- **`current-row-changed(`_`int`_`)`**: Emitted when the current row has changed because the user modified it
### Functions
- **`set-current-row(index: int)`: Sets the current row and brings it into view
### Example
```slint
import { StandardTableView } from "std-widgets.slint";
export component Example inherits Window {
width: 230px;
height: 200px;
StandardTableView {
width: 230px;
height: 200px;
columns: [
{ title: "Header 1" },
{ title: "Header 2" },
];
rows: [
[
{ text: "Item 1" }, { text: "Item 2" },
],
[
{ text: "Item 1" }, { text: "Item 2" },
],
[
{ text: "Item 1" }, { text: "Item 2" },
]
];
}
}
```

29
docs/reference/src/language/widgets/switch.md Normal file
View file

@ -0,0 +1,29 @@
## `Switch`
A `Switch` is a representation of a physical switch that allows users to turn things on or off. Consider using a `CheckBox` instead if you want the user to select or deselect values, for example in a list with multiple options.
### Properties
- **`checked`**: (_inout_ _bool_): Whether the switch is checked or not (default: false).
- **`enabled`**: (_in_ _bool_): Defaults to true. When false, the switch can't be pressed (default: true).
- **`has-focus`**: (_out_ _bool_): Set to true when the switch has keyboard focue (default: false).
- **`text`** (_in_ _string_): The text written next to the switch.
### Callbacks
- **`toggled()`**: The switch value changed
### Example
```slint
import { Switch } from "std-widgets.slint";
export component Example inherits Window {
width: 200px;
height: 25px;
Switch {
width: parent.width;
height: parent.height;
text: "Hello World";
}
}
```

44
docs/reference/src/language/widgets/tabwidget.md Normal file
View file

@ -0,0 +1,44 @@
## `TabWidget`
`TabWidget` is a container for a set of tabs. It can only have `Tab` elements as children and only one tab will be visible at
a time.
### Properties
- **`content-min-width`** and **`content-min-height`** (_out_ _length_): The minimum width and height of the contents
- **`content-width`** and **`content-height`** (_out_ _length_): The width and height of the contents
- **`content-x`** and **`content-y`** (_out_ _length_): The x and y position of the contents
- **`current-focused`** (_in_ _int_): The index of the tab that has focus. This tab may or may not be visible.
- **`current-index`** (_in_ _int_): The index of the currently visible tab
- **`tabbar-preferred-width`** and **`tabbar-preferred-height`** (_in_ _length_): The preferred width and height of the tab bar
- **`tabbar-width`** and **`tabbar-height`** (_out_ _length_): The width and height of the tab bar
- **`tabbar-x`** and **`tabbar-y`** (_out_ _length_): The x and y position of the tab bar
### Properties of the `Tab` element
- **`current-focused`** (_out_ _int_): The index of this tab that has focus at this time or -1 if none is focused
- **`enabled`**: (_in_ _bool_): Defaults to true. When false, the tab can't be activated
- **`icon`** (_in_ _image_): The image on the tab
- **`num-tabs`** (_out_ _int_): The number of tabs in the current `TabBar`
- **`tab-index`** (_out_ _int_): The index of this tab
- **`title`** (_in_ _string_): The text written on the tab
### Example
```slint
import { TabWidget } from "std-widgets.slint";
export component Example inherits Window {
width: 200px;
height: 200px;
TabWidget {
Tab {
title: "First";
Rectangle { background: orange; }
}
Tab {
title: "Second";
Rectangle { background: pink; }
}
}
}
```

45
docs/reference/src/language/widgets/textedit.md Normal file
View file

@ -0,0 +1,45 @@
## `TextEdit`
Similar to [`LineEdit`](#lineedit)`, but can be used to enter several lines of text
_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
- **`font-size`** (_in_ _length_): the size of the font of the input text
- **`text`** (_in-out_ _string_): The text being edited
- **`has-focus`**: (_in_out_ _bool_): Set to true when the widget currently has the focus
- **`enabled`**: (_in_ _bool_): Defaults to true. When false, nothing can be entered
- **`read-only`** (_in_ _bool_): When set to true, text editing via keyboard and mouse is disabled but selecting text is still enabled as well as editing text programmatically (default value: `false`)
- **`wrap`** (_in_ _enum [`TextWrap`](../builtins/enums.md#textwrap)_): The way the text wraps (default: word-wrap).
- **`horizontal-alignment`** (_in_ _enum [`TextHorizontalAlignment`](../builtins/enums.md#texthorizontalalignment)_): The horizontal alignment of the text.
### Functions
- **`focus()`** Call this function to focus the TextEdit and make it receive future keyboard events.
- **`select-all()`** Selects all text.
- **`clear-selection()`** Clears the selection.
- **`copy()`** Copies the selected text to the clipboard.
- **`cut()`** Copies the selected text to the clipboard and removes it from the editable area.
- **`paste()`** Pastes the text content of the clipboard at the cursor position.
### Callbacks
- **`edited(`_`string`_`)`**: Emitted when the text has changed because the user modified it
### Example
```slint
import { TextEdit } from "std-widgets.slint";
export component Example inherits Window {
width: 200px;
height: 200px;
TextEdit {
font-size: 14px;
width: parent.width;
height: parent.height;
text: "Lorem ipsum dolor sit amet,\n consectetur adipisici elit";
}
}
```

4
docs/reference/src/language/widgets/verticalbox.md Normal file
View file

@ -0,0 +1,4 @@
## `VerticalBox`
A `VerticalBox` is a [`VerticalLayout`](../builtins/elements.md#verticallayout-and-horizontallayout) where the spacing and padding values
depend on the style instead of defaulting to 0.

15
docs/reference/src/language/widgets/widgets.md Normal file
View file

@ -0,0 +1,15 @@
Slint provides a series of built-in widgets that can be imported from `"std-widgets.slint"`.
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.
See [Selecting a Widget Style](../../advanced/style.md#selecting-a-widget-style) for details how to select the style. If no style is selected, `native` is the default. If `native` isn't available, `fluent` is the default.
All widgets support all [properties common to builtin elements](../builtins/elements.md#common-properties).

18
internal/common/enums.rs
View file

@ -73,7 +73,7 @@ macro_rules! for_each_enums {
}
/// Use this enum to add standard buttons to a [`Dialog`](elements.md#dialog). The look and positioning
/// of these [`StandardButton`](widgets.md#standardbutton)s depends on the environment
/// of these [`StandardButton`](../widgets/standardbutton.md)s depends on the environment
/// (OS, UI environment, etc.) the application runs in.
enum StandardButtonKind {
/// A "OK" button that accepts a [`Dialog`](elements.md#dialog), closing it when clicked.
@ -246,7 +246,7 @@ macro_rules! for_each_enums {
}
/// Enum representing the [alignment](../concepts/layouting.md#alignment) property of a
/// [`HorizontalBox`](widgets.md#horizontalbox), a [`VerticalBox`](widgets.md#verticalbox),
/// [`HorizontalBox`](../widgets/horizontalbox.md), a [`VerticalBox`](../widgets/verticalbox.md),
/// a [`HorizontalLayout`, or `VerticalLayout`](elements.md#verticallayout-and-horizontallayout).
enum LayoutAlignment {
/// Use the minimum size of all elements in a layout, distribute remaining space
@ -290,24 +290,24 @@ macro_rules! for_each_enums {
enum AccessibleRole {
/// The element isn't accessible.
None,
/// The element is a [`Button`](widgets.md#button) or behaves like one.
/// The element is a [`Button`](../widgets/button.md) or behaves like one.
Button,
/// The element is a [`CheckBox`](widgets.md#checkbox) or behaves like one.
/// The element is a [`CheckBox`](../widgets/checkbox.md) or behaves like one.
Checkbox,
/// The element is a [`ComboBox`](widgets.md#combobox) or behaves like one.
/// The element is a [`ComboBox`](../widgets/combobox.md) or behaves like one.
Combobox,
/// The element is a [`Slider`](widgets.md#slider) or behaves like one.
/// The element is a [`Slider`](../widgets/slider.md) or behaves like one.
Slider,
/// The element is a [`SpinBox`](widgets.md#spinbox) or behaves like one.
/// The element is a [`SpinBox`](../widgets/spinbox.md) or behaves like one.
Spinbox,
/// The element is a [`Tab`](widgets.md#tabwidget) or behaves like one.
/// The element is a [`Tab`](../widgets/tabwidget.md) or behaves like one.
Tab,
/// The role for a [`Text`](elements.md#text) element. It's automatically applied.
Text,
}
/// This enum represents the different values of the `sort-order` property.
/// It's used to sort a [`StandardTableView`](widgets.md#standardtableview) by a column.
/// It's used to sort a [`StandardTableView`](../widgets/standardtableview.md) by a column.
enum SortOrder {
/// The column is unsorted.
Unsorted,