language-servers/slint
1
0
Fork 0
mirror of https://github.com/slint-ui/slint.git synced 2025-10-17 13:58:05 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 3

Minor updates to the documentation for readability and polish

Browse source
This commit is contained in:
Kavindra Palaraja 2025-04-22 21:04:34 +02:00 • committed by Simon Hausmann
parent 1800ed3018
commit cafa43ff22
1 changed files with 52 additions and 45 deletions
Download patch file Download diff file Expand all files Collapse all files

97
api/python/README.md
View file

@ -5,10 +5,10 @@
[Slint](https://slint.dev/) is a UI toolkit that supports different programming languages. [Slint](https://slint.dev/) is a UI toolkit that supports different programming languages.
Slint-python is the integration with Python. Slint-python is the integration with Python.
**Warning: Beta** **Warning**
Slint-python is in a beta phase of development: The APIs are mostly stable but may be subject to further changes. Any changes will be documented in the ChangeLog. Slint-python is in a beta phase of development: The APIs while mostly stable, may be subject to further changes. Any changes will be documented in the ChangeLog.
You can track the overall progress for the Python integration by looking at python-labelled issues at https://github.com/slint-ui/slint/labels/a%3Alanguage-python . You can track the progress for the Python integration by looking at python-labelled issues at https://github.com/slint-ui/slint/labels/a%3Alanguage-python .
## Slint Language Manual ## Slint Language Manual
@ -24,17 +24,18 @@ in detail.
Slint can be installed with `uv` or `pip` from the [Python Package Index](https://pypi.org): Slint can be installed with `uv` or `pip` from the [Python Package Index](https://pypi.org):
``` ```bash
uv add slint uv add slint
``` ```
The installation will use binaries provided vi macOS, Windows, and Linux for various architectures. If your target platform is not covered by binaries, The installation uses binaries provided for macOS, Windows, and Linux for various architectures. If your target platform
`uv` will automatically build Slint from source. If that happens, you need common software development tools on your machine, as well as [Rust](https://www.rust-lang.org/learn/get-started). is not covered by binaries, `uv` will automatically build Slint from source. If that happens, you will then need some
software development tools on your machine, as well as [Rust](https://www.rust-lang.org/learn/get-started).
## Quick Start ## Quick Start
1. Create a new project with `uv init`. 1. Create a new project with `uv init`.
2. Add Slint Python Package Index to your Python project: `uv add slint` 2. Add the Slint Python package to your Python project: `uv add slint`
3. Create a file called `app-window.slint`: 3. Create a file called `app-window.slint`:
```slint ```slint
@ -95,11 +96,11 @@ export component MainWindow inherits Window {
} }
``` ```
The exported component is exposed as a Python class. To access this class, you have two The exported component is exposed as a Python class. To access this class, you have two options:
options:
1. Call `slint.load_file("app.slint")`. The returned object is a [namespace](https://docs.python.org/3/library/types.html#types.SimpleNamespace), 1. Call `slint.load_file("app.slint")`. The returned object is a [namespace](https://docs.python.org/3/library/types.html#types.SimpleNamespace),
that provides the `MainWindow` class as well as any other explicitly exported component that inherits `Window`: that provides the `MainWindow` class as well as any other explicitly exported component that inherits `Window`:
```python ```python
import slint import slint
components = slint.load_file("app.slint") components = slint.load_file("app.slint")
@ -107,21 +108,26 @@ options:
``` ```
2. Use Slint's auto-loader, which lazily loads `.slint` files from `sys.path`: 2. Use Slint's auto-loader, which lazily loads `.slint` files from `sys.path`:
```python ```python
import slint import slint
# Look for for `app.slint` in `sys.path`: # Look for for `app.slint` in `sys.path`:
main_window = slint.loader.app.MainWindow() main_window = slint.loader.app.MainWindow()
``` ```
Any attribute lookup in `slint.loader` is searched for in `sys.path`. If a directory with the name exists, it is returned as a loader object, and subsequent Any attribute lookup in `slint.loader` is searched for in `sys.path`. If a directory with the name exists, it is
attribute lookups follow the same logic. If the name matches a file with the `.slint` extension, it is automatically loaded with `load_file` and the returned as a loader object, and subsequent attribute lookups follow the same logic.
[namespace](https://docs.python.org/3/library/types.html#types.SimpleNamespace) is returned, which contains classes for each exported component that
inherits `Window`. If the file name contains a dash, like `app-window.slint`, an attribute lookup for `app_window` will If the name matches a file with the `.slint` extension, it is automatically loaded with `load_file` and the
first try to locate `app_window.slint` and then fall back to `app-window.slint`. [namespace](https://docs.python.org/3/library/types.html#types.SimpleNamespace) is returned.
If the file name contains a dash, like `app-window.slint`, an attribute lookup for `app_window` tries to
locate `app_window.slint` and then fall back to `app-window.slint`.
### Accessing Properties ### Accessing Properties
[Properties](../slint/src/language/syntax/properties) declared as `out` or `in-out` in `.slint` files are visible as properties on the component instance. [Properties](../slint/src/language/syntax/properties) declared as `out` or `in-out` in `.slint` files are visible as
properties on the component instance.
```python ```python
main_window.counter = 42 main_window.counter = 42
@ -148,15 +154,15 @@ print("job count:", instance.PrinterJobQueue.job_count)
``` ```
**Note**: Global singletons are instantiated once per component. When declaring multiple components for `export` to Python, **Note**: Global singletons are instantiated once per component. When declaring multiple components for `export` to Python,
each instance will have their own instance of associated globals singletons. each instance has their own associated globals singletons.
### Setting and Invoking Callbacks ### Setting and Invoking Callbacks
[Callbacks](src/language/syntax/callbacks) declared in `.slint` files are visible as callable properties on the component instance. Invoke them [Callbacks](src/language/syntax/callbacks) declared in `.slint` files are visible as callable properties on the component
as function to invoke the callback, and assign Python callables to set the callback handler. instance. Invoke them as functions to invoke the callback, and assign Python callables to set the callback handler.
Callbacks in Slint can be defined using the `callback` keyword and can be connected to a callback of an other component In Slint, callbacks are defined using the `callback` keyword and can be connected to another component's callback using
using the `<=>` syntax. the `<=>` syntax.
**`my-component.slint`** **`my-component.slint`**
@ -171,7 +177,7 @@ export component MyComponent inherits Window {
} }
``` ```
The callbacks in Slint are exposed as properties and that can be called as a function. The callbacks in Slint are exposed as properties and that can be called as functions.
**`main.py`** **`main.py`**
@ -202,35 +208,36 @@ class Component(slint.loader.my_component.MyComponent):
component = Component() component = Component()
``` ```
The `@slint.callback()` decorator accepts a `name` named argument, when the name of the method The `@slint.callback()` decorator accepts a `name` argument, if the name of the method does not match the name of the
does not match the name of the callback in the `.slint` file. Similarly, a `global_name` argument callback in the `.slint` file. Similarly, a `global_name` argument can be used to bind a method to a callback in a global
can be used to bind a method to a callback in a global singleton. singleton.
### Type Mappings ### Type Mappings
The types used for properties in the Slint Language each translate to specific types in Python. The follow table summarizes the entire mapping: Each type used for properties in the Slint Language translates to a specific type in Python. The following table summarizes
the mapping:
| `.slint` Type | Python Type | Notes | | `.slint` Type | Python Type | Notes |
| --- | --- | --- | | ------------- | ----------- | ----- |
| `int` | `int` | | | `int` | `int` | |
| `float` | `float` | | | `float` | `float` | |
| `string` | `str` | | | `string` | `str` | |
| `color` | `slint.Color` | | | `color` | `slint.Color` | |
| `brush` | `slint.Brush` | | | `brush` | `slint.Brush` | |
| `image` | `slint.Image` | | | `image` | `slint.Image` | |
| `length` | `float` | | | `length` | `float` | |
| `physical_length` | `float` | | | `physical_length` | `float` | |
| `duration` | `float` | The number of milliseconds | | `duration` | `float` | The number of milliseconds |
| `angle` | `float` | The angle in degrees | | `angle` | `float` | The angle in degrees |
| structure | `dict`/`Struct` | When reading, structures are mapped to data classes, when writing dicts are also accepted. | | structure | `dict`/`Struct` | When reading, structures are mapped to data classes, when writing dicts are also accepted. |
| array | `slint.Model` | | | array | `slint.Model` | |
### Arrays and Models ### Arrays and Models
[Array properties](../slint/src/language/syntax/types#arrays-and-models) can be set from Python by passing You can set [array properties](../slint/src/language/syntax/types#arrays-and-models) from Python by passing subclasses of
subclasses of `slint.Model`. `slint.Model`.
Use the `slint.ListModel` class to construct a model from an iterable. Use the `slint.ListModel` class to construct a model from an iterable:
```python ```python
component.model = slint.ListModel([1, 2, 3]); component.model = slint.ListModel([1, 2, 3]);
@ -253,12 +260,12 @@ When sub-classing `slint.Model`, provide the following methods:
self.notify_row_changed(row) self.notify_row_changed(row)
``` ```
When adding/inserting rows, call `notify_row_added(row, count)` on the super class. Similarly, removal When adding or inserting rows, call `notify_row_added(row, count)` on the super class. Similarly, when removing rows, notify
requires notifying Slint by calling `notify_row_removed(row, count)`. Slint by calling `notify_row_removed(row, count)`.
### Structs ### Structs
Structs declared in Slint and exposed to Python via `export` are accessible in the namespace returned Structs declared in Slint and exposed to Python via `export` are then accessible in the namespace that is returned
when [instantiating a component](#instantiating-a-component). when [instantiating a component](#instantiating-a-component).
**`app.slint`** **`app.slint`**
@ -276,7 +283,7 @@ export component MainWindow inherits Window {
**`main.py`** **`main.py`**
The exported `MyData` struct can be constructed The exported `MyData` struct can be constructed as follows:
```python ```python
import slint import slint