-
Notifications
You must be signed in to change notification settings - Fork 617
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
1.9 docs: Add in missing globals (#7061)
- Loading branch information
1 parent
8997f2c
commit f64afc2
Showing
7 changed files
with
266 additions
and
116 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
7 changes: 0 additions & 7 deletions
7
docs/astro/src/content/docs/guide/development/accessibility.mdx
This file was deleted.
Oops, something went wrong.
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 |
|---|---|---|
| @@ -1,7 +1,7 @@ | ||
| --- | ||
| <!-- Copyright © SixtyFPS GmbH <[email protected]> ; SPDX-License-Identifier: MIT --> | ||
| title: Reference Overview | ||
| description: Reference Overview | ||
| title: Common Properties & Callbacks | ||
| description: Common Properties & Callbacks | ||
| --- | ||
|
|
||
| import SlintProperty from '/src/components/SlintProperty.astro'; | ||
|
|
@@ -11,79 +11,15 @@ import Link from '/src/components/Link.astro'; | |
| The Slint elements have many common properties, callbacks and behavior. | ||
| This page describes these properties and their usage. | ||
|
|
||
| ## `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 | ||
| invocation is from inside to outside. The following example will print "first", then "second", and then "third": | ||
|
|
||
| ```slint | ||
| component MyButton inherits Rectangle { | ||
| in-out property <string> text: "Initial"; | ||
| init => { | ||
| // If `text` is queried here, it will have the value "Hello". | ||
| debug("first"); | ||
| } | ||
| } | ||
| component MyCheckBox inherits Rectangle { | ||
| init => { debug("second"); } | ||
| } | ||
| export component MyWindow inherits Window { | ||
| MyButton { | ||
| text: "Hello"; | ||
| init => { debug("third"); } | ||
| } | ||
| MyCheckBox { | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| Don't use this callback to initialize properties, because this violates the declarative principle. | ||
|
|
||
| Even though the `init` callback exists on all components, it cannot be set from application code, | ||
| i.e. an `on_init` function does not exist in the generated code. This is because the callback is invoked during the creation of the component, before you could call `on_init` to actually set it. | ||
|
|
||
| While the `init` callback can invoke other callbacks, e.g. one defined in a `global` section, and | ||
| you _can_ bind these in the backend, this doesn't work for statically-created components, including | ||
| the window itself, because you need an instance to set the globals binding. But it is possible | ||
| to use this for dynamically created components (for example ones behind an `if`): | ||
| ## Common Visual Properties | ||
|
|
||
| ```slint | ||
| export global SystemService { | ||
| // This callback can be implemented in native code using the Slint API | ||
| callback ensure_service_running(); | ||
| } | ||
| component MySystemButton inherits Rectangle { | ||
| init => { | ||
| SystemService.ensure_service_running(); | ||
| } | ||
| // ... | ||
| } | ||
| These properties are valid on all visual items. For example `Rectangle`, `Text`, and `layouts`. Non | ||
| visual items such as `Timer` don't have these properties. | ||
|
|
||
| export component AppWindow inherits Window { | ||
| in property <bool> show-button: false; | ||
|
|
||
| // MySystemButton isn't initialized at first, only when show-button is set to true. | ||
| // At that point, its init callback will call ensure_service_running() | ||
| if show-button : MySystemButton {} | ||
| } | ||
| ``` | ||
|
|
||
|
|
||
| ## Geometry | ||
|
|
||
| These properties are valid on all **visible** items: | ||
|
|
||
| ### x | ||
| <SlintProperty propName="x" typeName="length" > | ||
| The position of the element relative to its parent. | ||
| </SlintProperty> | ||
|
|
||
| ### y | ||
| <SlintProperty propName="y" typeName="length" > | ||
| ### x, y | ||
| <SlintProperty propName="x, y" typeName="length" > | ||
| The position of the element relative to its parent. | ||
| </SlintProperty> | ||
|
|
||
|
|
@@ -92,31 +28,18 @@ The position of the element relative to its parent. | |
| Allows to specify a different order to stack the items with its siblings. | ||
| The value must be a compile time constant. | ||
|
|
||
| :::caution[Caution] | ||
| :::note[Note] | ||
| Currently the `z` value is a compile time constant and cannot be changed at runtime. | ||
| ::: | ||
|
|
||
| </SlintProperty> | ||
|
|
||
| ### absolute-position | ||
| <SlintProperty propName="absolute-position" typeName="struct" structName="Point" propertyVisibility="out"> | ||
|
|
||
| Represents a point specifying an absolute position within a window or popup window. | ||
| It defines coordinates (x,y) relative to the enclosing Window or PopupWindow, but the reference frame is unspecified | ||
| (could be screen, window, or popup coordinates). | ||
| This property is only absolute within the enclosing Window or PopupWindow. | ||
|
|
||
| </SlintProperty> | ||
|
|
||
| ### width | ||
| <SlintProperty propName="width" typeName="length" > | ||
| The width of the element. When set, this overrides the default width. | ||
| ### width, height | ||
| <SlintProperty propName="width, height" typeName="length" > | ||
| The width and height of the element. When set, this overrides the default size. | ||
| </SlintProperty> | ||
|
|
||
| ### height | ||
| <SlintProperty propName="height" typeName="length" > | ||
| The height of the element. When set, this overrides the default height. | ||
| </SlintProperty> | ||
|
|
||
| ### opacity | ||
| <SlintProperty propName="opacity" typeName="float" defaultValue="1"> | ||
|
|
@@ -126,9 +49,9 @@ the element and its children with transparency. | |
| The opacity is applied to the tree of child elements as if they | ||
| were first drawn into an intermediate layer, and then the whole layer is rendered with this opacity. | ||
|
|
||
| :::caution[Caution] | ||
| :::tip[Tip] | ||
| When an element has 0 opacity it will still take up layout space and any gesture handling will continue | ||
| to work. If the intent is to hide an element so it has no gesture handling or takes up layout space, | ||
| to work. If the intent is to hide an element so it has no gesture handling or no longer takes up layout space, | ||
| use the `visible` property instead. | ||
| ::: | ||
| </SlintProperty> | ||
|
|
@@ -161,6 +84,16 @@ Rectangle { | |
| </CodeSnippetMD> | ||
| </SlintProperty> | ||
|
|
||
| ### absolute-position | ||
| <SlintProperty propName="absolute-position" typeName="struct" structName="Point" propertyVisibility="out"> | ||
|
|
||
| A common issue is that in a UI with many nested components it's useful to know their (x,y)position relative to | ||
| the main window or screen. This convienience property gives easy read only access to that value. | ||
|
|
||
| It represents a point specifying the absolute position within the enclosing <Link type="Window"/> or <Link type="PopupWindow"/>. | ||
| It defines coordinates (x,y) relative to the enclosing Window or PopupWindow, but the reference frame is unspecified | ||
| (could be screen, window, or popup coordinates). | ||
| </SlintProperty> | ||
|
|
||
| ## Layout | ||
|
|
||
|
|
@@ -182,14 +115,77 @@ change this may speed up the rendering, at the expense of increased memory consu | |
| all rendering backends support this, so this is merely a hint. | ||
| </SlintProperty> | ||
|
|
||
|
|
||
|
|
||
| ### dialog-button-role | ||
| <SlintProperty typeName="enum" enumName="DialogButtonRole"> | ||
| <SlintProperty typeName="enum" enumName="DialogButtonRole" defaultValue="none"> | ||
| Specify that this is a button in a `Dialog`. | ||
| </SlintProperty> | ||
|
|
||
| ## Common 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 | ||
| invocation is from inside to outside. The following example will print "first", then "second", and then "third": | ||
|
|
||
| ```slint | ||
| component MyButton inherits Rectangle { | ||
| in-out property <string> text: "Initial"; | ||
| init => { | ||
| // If `text` is queried here, it will have the value "Hello". | ||
| debug("first"); | ||
| } | ||
| } | ||
| component MyCheckBox inherits Rectangle { | ||
| init => { debug("second"); } | ||
| } | ||
| export component MyWindow inherits Window { | ||
| MyButton { | ||
| text: "Hello"; | ||
| init => { debug("third"); } | ||
| } | ||
| MyCheckBox { | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| Don't use this callback to initialize properties, because this violates the declarative principle. | ||
|
|
||
| Even though the `init` callback exists on all components, it cannot be set from application code, | ||
| i.e. an `on_init` function does not exist in the generated code. This is because the callback is invoked during the creation of the component, before you could call `on_init` to actually set it. | ||
|
|
||
| While the `init` callback can invoke other callbacks, e.g. one defined in a `global` section, and | ||
| you _can_ bind these in the backend, this doesn't work for statically-created components, including | ||
| the window itself, because you need an instance to set the globals binding. But it is possible | ||
| to use this for dynamically created components (for example ones behind an `if`): | ||
|
|
||
| ## Accessibility | ||
| ```slint | ||
| export global SystemService { | ||
| // This callback can be implemented in native code using the Slint API | ||
| callback ensure_service_running(); | ||
| } | ||
| component MySystemButton inherits Rectangle { | ||
| init => { | ||
| SystemService.ensure_service_running(); | ||
| } | ||
| // ... | ||
| } | ||
| export component AppWindow inherits Window { | ||
| in property <bool> show-button: false; | ||
| // MySystemButton isn't initialized at first, only when show-button is set to true. | ||
| // At that point, its init callback will call ensure_service_running() | ||
| if show-button : MySystemButton {} | ||
| } | ||
| ``` | ||
|
|
||
| ## Accessibility Properties | ||
|
|
||
| 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` must be set in order to be able to set any other accessible property or callback. | ||
|
|
@@ -269,13 +265,18 @@ Whether the element is selected or not. This maps to the "is-selected" state of | |
| The total number of elements in a group. Applies to the parent container of a group of element such as list views, radio button groups or other grouping elements. | ||
| </SlintProperty> | ||
|
|
||
| You can also use the following callbacks that are going to be called by the accessibility framework: | ||
|
|
||
| - **`accessible-action-default()`**: Invoked when the default action for this widget is requested (eg: pressed for a button). | ||
| - **`accessible-action-set-value(string)`**: Invoked when the user wants to change the accessible value. | ||
| - **`accessible-action-increment()`**: Invoked when the user requests to increment the value. | ||
| - **`accessible-action-decrement()`**: Invoked when the user requests to decrement the value. | ||
| ## Accessibility Callbacks | ||
| You can also use the following callbacks that are going to be called by the accessibility framework: | ||
|
|
||
| ### accessible-action-default() | ||
| Invoked when the default action for this widget is requested (eg: pressed for a button). | ||
|
|
||
| ### accessible-action-set-value(string) | ||
| Invoked when the user wants to change the accessible value. | ||
|
|
||
| ### accessible-action-increment() | ||
| Invoked when the user requests to increment the value. | ||
|
|
||
| ### accessible-action-decrement() | ||
| Invoked when the user requests to decrement the value. | ||
File renamed without changes.
File renamed without changes.
Oops, something went wrong.