-
Notifications
You must be signed in to change notification settings - Fork 604
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
b5b82c7
commit 4775473
Showing
3 changed files
with
206 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,49 @@ | ||
--- | ||
title: Dialog | ||
description: Dialog element api. | ||
--- | ||
import SlintProperty from '../../../components/SlintProperty.astro'; | ||
|
||
```slint title="dialog-example.slint" | ||
import { StandardButton, Button } from "std-widgets.slint"; | ||
export component Example inherits Dialog { | ||
Text { | ||
text: "This is a dialog box"; | ||
} | ||
StandardButton { kind: ok; } | ||
StandardButton { kind: cancel; } | ||
Button { | ||
text: "More Info"; | ||
dialog-button-role: action; | ||
} | ||
} | ||
``` | ||
|
||
Dialog is like a window, but it has buttons that are automatically laid out. | ||
|
||
A Dialog should have one main element as child, that isn't a button. | ||
The dialog can have any number of `StandardButton` widgets or other buttons | ||
with the `dialog-button-role` property. | ||
The buttons will be placed in an order that depends on the target platform at run-time. | ||
|
||
The `kind` property of the `StandardButton`s and the `dialog-button-role` properties need to be set to a constant value, it can't be an arbitrary variable expression. | ||
There can't be several `StandardButton`s of the same kind. | ||
|
||
A callback `<kind>_clicked` is automatically added for each `StandardButton` which doesn't have an explicit | ||
callback handler, so it can be handled from the native code: For example if there is a button of kind `cancel`, | ||
a `cancel_clicked` callback will be added. | ||
Each of these automatically-generated callbacks is an alias for the `clicked` callback of the associated `StandardButton`. | ||
|
||
## Properties | ||
|
||
|
||
### `icon` | ||
<SlintProperty propName="icon" typeName="image"> | ||
The window icon shown in the title bar or the task bar on window managers supporting it. | ||
</SlintProperty> | ||
|
||
|
||
### `title` | ||
<SlintProperty propName="icon" typeName="string"> | ||
The window title that is shown in the title bar. | ||
</SlintProperty> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,90 @@ | ||
--- | ||
title: Flickable | ||
description: Flickable element api. | ||
--- | ||
import SlintProperty from '../../../components/SlintProperty.astro'; | ||
|
||
```slint | ||
export component Example inherits Window { | ||
width: 270px; | ||
height: 100px; | ||
Flickable { | ||
viewport-height: 300px; | ||
Text { | ||
x:0; | ||
y: 150px; | ||
text: "This is some text that you have to scroll to see"; | ||
} | ||
} | ||
} | ||
``` | ||
|
||
The `Flickable` is a low-level element that is the base for scrollable | ||
widgets, such as the [`ScrollView`](scrollview). 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 | ||
calculated automatically based on the `Flickable`'s children. This isn't the | ||
case when using a `for` loop to populate the elements. This is a bug tracked in | ||
issue [#407](https://github.com/slint-ui/slint/issues/407). | ||
The maximum and preferred size of the `Flickable` are based on the viewport. | ||
|
||
When not part of a layout, its width or height defaults to 100% of the parent | ||
element when not specified. | ||
|
||
## Pointer Event Interaction | ||
|
||
If the `Flickable`'s area contains elements that use `TouchArea` to act on clicking, such as `Button` | ||
widgets, then the following algorithm is used to distinguish between the user's intent of scrolling or | ||
interacting with `TouchArea` elements: | ||
|
||
1. If the `Flickable`'s `interactive` property is `false`, all events are forwarded to elements underneath. | ||
2. If a press event is received where the event's coordinates interact with a `TouchArea`, the event is stored | ||
and any subsequent move and release events are handled as follows: | ||
1. If 100ms elapse without any events, the stored press event is delivered to the `TouchArea`. | ||
2. If a release event is received before 100ms have elapsed, the stored press event as well as the | ||
release event are immediately delivered to the `TouchArea` and the algorithm resets. | ||
3. Any move events received will start a flicking operation on the `Flickable` if all of the following | ||
conditions are met: | ||
1. The event is received before 500ms have elapsed since receiving the press event. | ||
2. The distance to the press event exceeds 8 logical pixels in an orientation in which we are allowed to move. | ||
If `Flickable` decides to flick, any press event sent previously to a `TouchArea`, is followed up | ||
by an exit event. During the phase of receiving move events, the flickable follows the coordinates. | ||
3. If the interaction of press, move, and release events begins at coordinates that do not intersect with | ||
a `TouchArea`, then `Flickable` will flick immediately on pointer move events when the euclidean distance | ||
to the coordinates of the press event exceeds 8 logical pixels. | ||
|
||
## Properties | ||
|
||
### `interactive` | ||
<SlintProperty propName="icon" typeName="bool" defaultValue="true"> | ||
When true, the viewport can be scrolled by clicking on it and dragging it with the cursor. | ||
</SlintProperty> | ||
|
||
### `viewport-width` | ||
<SlintProperty propName="viewport-width" typeName="length"> | ||
The total width of the scrollable element. | ||
</SlintProperty> | ||
|
||
### `viewport-height` | ||
<SlintProperty propName="viewport-height" typeName="length"> | ||
The total height of the scrollable element. | ||
</SlintProperty> | ||
|
||
|
||
### `viewport-x` | ||
<SlintProperty propName="viewport-x" typeName="length"> | ||
The position of the scrollable element relative to the `Flickable`. This is usually a negative value. | ||
</SlintProperty> | ||
|
||
|
||
### `viewport-y` | ||
<SlintProperty propName="viewport-y" typeName="length"> | ||
The position of the scrollable element relative to the `Flickable`. This is usually a negative value. | ||
</SlintProperty> | ||
|
||
## Callbacks | ||
|
||
### `flicked()` | ||
Invoked when `viewport-x` or `viewport-y` is changed by a user action (dragging, scrolling). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,67 @@ | ||
--- | ||
title: FocusScope | ||
description: FocusScope element api. | ||
--- | ||
import SlintProperty from '../../../components/SlintProperty.astro'; | ||
|
||
```slint | ||
export component Example inherits Window { | ||
width: 100px; | ||
height: 100px; | ||
forward-focus: my-key-handler; | ||
my-key-handler := FocusScope { | ||
key-pressed(event) => { | ||
debug(event.text); | ||
if (event.modifiers.control) { | ||
debug("control was pressed during this event"); | ||
} | ||
if (event.text == Key.Escape) { | ||
debug("Esc key was pressed") | ||
} | ||
accept | ||
} | ||
} | ||
} | ||
``` | ||
|
||
The `FocusScope` exposes callbacks to intercept key events. Note that `FocusScope` | ||
will only invoke them when it `has-focus`. | ||
|
||
The [`KeyEvent`](structs.md#keyevent) has a text property, which is a character of the key entered. | ||
When a non-printable key is pressed, the character will be either a control character, | ||
or it will be mapped to a private unicode character. The mapping of these non-printable, special characters is available in the [`Key`](namespaces.md#key) namespace | ||
|
||
## Properties | ||
|
||
### `has-focus` | ||
<SlintProperty propName="has-focus" typeName="bool" defaultValue="false" PropertyVisibility="out"> | ||
Is `true` when the element has keyboard focus. | ||
</SlintProperty> | ||
|
||
### `enabled` | ||
<SlintProperty propName="enabled" typeName="bool" defaultValue="true"> | ||
When true, the `FocusScope` will make itself the focused element when clicked. Set this to false if you don't want the click-to-focus | ||
behavior. Similarly, a disabled `FocusScope` does not accept the focus via tab focus traversal. A parent `FocusScope` will still receive key events from | ||
child `FocusScope`s that were rejected, even if `enabled` is set to false. | ||
</SlintProperty> | ||
|
||
## Functions | ||
|
||
### `focus()` | ||
Call this function to transfer keyboard focus to this `FocusScope`, to receive future [`KeyEvent`](structs.md#keyevent)s. | ||
|
||
### `clear-focus()` | ||
Call this function to remove keyboard focus from this `FocusScope` if it currently has the focus. See also [](../concepts/focus.md). | ||
|
||
## Callbacks | ||
|
||
### `key-pressed(KeyEvent) -> EventResult` | ||
Invoked when a key is pressed, the argument is a [`KeyEvent`](structs.md#keyevent) struct. The returned [`EventResult`](enums.md#eventresult) | ||
indicates whether to accept or ignore the event. Ignored events are forwarded to the parent element. | ||
|
||
### `key-released(KeyEvent) -> EventResult` | ||
Invoked when a key is released, the argument is a [`KeyEvent`](structs.md#keyevent) struct. The returned [`EventResult`](enums.md#eventresult) | ||
indicates whether to accept or ignore the event. Ignored events are forwarded to the parent element. | ||
|
||
### `focus-changed-event()` | ||
Invoked when the focus on the `FocusScope` has changed. |