From f64afc2588a1fc5d435922c63eea5cc6965db93b Mon Sep 17 00:00:00 2001 From: Nigel Breslaw Date: Wed, 11 Dec 2024 12:49:57 +0200 Subject: [PATCH] 1.9 docs: Add in missing globals (#7061) --- docs/astro/astro.config.mjs | 22 +- .../docs/guide/development/accessibility.mdx | 7 - .../src/content/docs/reference/common.mdx | 253 +++++++++--------- .../builtinfunctions.mdx | 0 .../math.mdx | 0 .../docs/reference/global-structs-enums.mdx | 148 ++++++++++ docs/astro/src/utils/link-data.json | 10 +- 7 files changed, 295 insertions(+), 145 deletions(-) delete mode 100644 docs/astro/src/content/docs/guide/development/accessibility.mdx rename docs/astro/src/content/docs/reference/{global-functions-enums => global-functions}/builtinfunctions.mdx (100%) rename docs/astro/src/content/docs/reference/{global-functions-enums => global-functions}/math.mdx (100%) diff --git a/docs/astro/astro.config.mjs b/docs/astro/astro.config.mjs index a2b4858fe..b85d5219e 100644 --- a/docs/astro/astro.config.mjs +++ b/docs/astro/astro.config.mjs @@ -143,10 +143,6 @@ export default defineConfig({ "guide/development/focus", "guide/development/translations", "guide/development/fonts", - { - label: "Accessibility", - slug: "guide/development/accessibility", - }, { label: "Custom Controls", slug: "guide/development/custom-controls", @@ -165,9 +161,15 @@ export default defineConfig({ { label: "Backends and Renderers", collapsed: true, - autogenerate: { - directory: "guide/backends-and-renderers", - }, + items: [ + { + label: "Overview", + slug: "guide/backends-and-renderers/backends_and_renderers", + }, + "guide/backends-and-renderers/backend_linuxkms", + "guide/backends-and-renderers/backend_qt", + "guide/backends-and-renderers/backend_winit", + ], }, ], }, @@ -260,16 +262,16 @@ export default defineConfig({ slug: "reference/global-structs-enums", }, { - label: "Global Functions and Enums", + label: "Global Functions", collapsed: true, items: [ { label: "Math", - slug: "reference/global-functions-enums/math", + slug: "reference/global-functions/math", }, { label: "animation-tick() / debug()", - slug: "reference/global-functions-enums/builtinfunctions", + slug: "reference/global-functions/builtinfunctions", }, ], }, diff --git a/docs/astro/src/content/docs/guide/development/accessibility.mdx b/docs/astro/src/content/docs/guide/development/accessibility.mdx deleted file mode 100644 index 85f8e3cb6..000000000 --- a/docs/astro/src/content/docs/guide/development/accessibility.mdx +++ /dev/null @@ -1,7 +0,0 @@ ---- - -title: Accessibility -description: Accessibility ---- - -Todo: Was this for after 1.9 as we have no docs beyond the list of accessibility properties in the common properties? diff --git a/docs/astro/src/content/docs/reference/common.mdx b/docs/astro/src/content/docs/reference/common.mdx index 425e3fbe2..282645269 100644 --- a/docs/astro/src/content/docs/reference/common.mdx +++ b/docs/astro/src/content/docs/reference/common.mdx @@ -1,7 +1,7 @@ --- -title: Reference Overview -description: Reference Overview +title: Common Properties & Callbacks +description: Common Properties & Callbacks --- import SlintProperty from '/src/components/SlintProperty.astro'; @@ -11,7 +11,120 @@ 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()` + +## Common Visual Properties + +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. + + +### x, y + +The position of the element relative to its parent. + + +### z + +Allows to specify a different order to stack the items with its siblings. +The value must be a compile time constant. + +:::note[Note] +Currently the `z` value is a compile time constant and cannot be changed at runtime. +::: + + + + +### width, height + +The width and height of the element. When set, this overrides the default size. + + + +### opacity + +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. +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. + +:::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 no longer takes up layout space, +use the `visible` property instead. +::: + + +### visible + +When set to `false`, the element and all his children won't be drawn and not react to mouse input. + +The following example demonstrates the `opacity` property with children. An opacity is applied to the red rectangle. Since the green rectangle is a child of the red one, you can see the gradient underneath it, but you can't see the red rectangle through the green one. + +```slint +Rectangle { + x: 10px; + y: 10px; + width: 180px; + height: 180px; + background: #315afd; + opacity: 0.5; +} + +Rectangle { + x: 10px; + y: 210px; + width: 180px; + height: 180px; + background: green; + opacity: 0.5; +} +``` + + + +### absolute-position + + +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 or . +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). + + +## Layout + +These properties are valid on all visible items and can be used to specify constraints when used in layouts: + +- **`col`**, **`row`**, **`colspan`**, **`rowspan`** (_in_ _int_): See . +- **`horizontal-stretch`** and **`vertical-stretch`** (_in-out_ _float_): Specify how much relative space these elements are stretching in a layout. When 0, this means that the elements won't be stretched unless all elements are 0. Builtin widgets have a value of either 0 or 1. +- **`max-width`** and **`max-height`** (_in_ _length_): The maximum size of an element +- **`min-width`** and **`min-height`** (_in_ _length_): The minimum size of an element +- **`preferred-width`** and **`preferred-height`** (_in_ _length_): The preferred size of an element + +## Miscellaneous + +### cache-rendering-hint + +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. + + + + +### dialog-button-role + +Specify that this is a button in a `Dialog`. + + +## 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 @@ -72,124 +185,7 @@ export component AppWindow inherits Window { } ``` - -## Geometry - -These properties are valid on all **visible** items: - -### x - -The position of the element relative to its parent. - - -### y - -The position of the element relative to its parent. - - -### z - -Allows to specify a different order to stack the items with its siblings. -The value must be a compile time constant. - -:::caution[Caution] -Currently the `z` value is a compile time constant and cannot be changed at runtime. -::: - - - -### absolute-position - - -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. - - - -### width - -The width of the element. When set, this overrides the default width. - - -### height - -The height of the element. When set, this overrides the default height. - - -### opacity - -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. -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] -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, -use the `visible` property instead. -::: - - -### visible - -When set to `false`, the element and all his children won't be drawn and not react to mouse input. - -The following example demonstrates the `opacity` property with children. An opacity is applied to the red rectangle. Since the green rectangle is a child of the red one, you can see the gradient underneath it, but you can't see the red rectangle through the green one. - -```slint -Rectangle { - x: 10px; - y: 10px; - width: 180px; - height: 180px; - background: #315afd; - opacity: 0.5; -} - -Rectangle { - x: 10px; - y: 210px; - width: 180px; - height: 180px; - background: green; - opacity: 0.5; -} -``` - - - - -## Layout - -These properties are valid on all visible items and can be used to specify constraints when used in layouts: - -- **`col`**, **`row`**, **`colspan`**, **`rowspan`** (_in_ _int_): See . -- **`horizontal-stretch`** and **`vertical-stretch`** (_in-out_ _float_): Specify how much relative space these elements are stretching in a layout. When 0, this means that the elements won't be stretched unless all elements are 0. Builtin widgets have a value of either 0 or 1. -- **`max-width`** and **`max-height`** (_in_ _length_): The maximum size of an element -- **`min-width`** and **`min-height`** (_in_ _length_): The minimum size of an element -- **`preferred-width`** and **`preferred-height`** (_in_ _length_): The preferred size of an element - -## Miscellaneous - -### cache-rendering-hint - -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. - - -### dialog-button-role - -Specify that this is a button in a `Dialog`. - - - - -## Accessibility +## 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. + +## 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. - +### 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. diff --git a/docs/astro/src/content/docs/reference/global-functions-enums/builtinfunctions.mdx b/docs/astro/src/content/docs/reference/global-functions/builtinfunctions.mdx similarity index 100% rename from docs/astro/src/content/docs/reference/global-functions-enums/builtinfunctions.mdx rename to docs/astro/src/content/docs/reference/global-functions/builtinfunctions.mdx diff --git a/docs/astro/src/content/docs/reference/global-functions-enums/math.mdx b/docs/astro/src/content/docs/reference/global-functions/math.mdx similarity index 100% rename from docs/astro/src/content/docs/reference/global-functions-enums/math.mdx rename to docs/astro/src/content/docs/reference/global-functions/math.mdx diff --git a/docs/astro/src/content/docs/reference/global-structs-enums.mdx b/docs/astro/src/content/docs/reference/global-structs-enums.mdx index 060f4783c..1ce7ff5d6 100644 --- a/docs/astro/src/content/docs/reference/global-structs-enums.mdx +++ b/docs/astro/src/content/docs/reference/global-structs-enums.mdx @@ -3,3 +3,151 @@ title: Global Structs and Enums description: Global Structs and Enums --- + + +import FontMetrics from "../../collections/structs/FontMetrics.md" +import KeyboardModifiers from "../../collections/structs/KeyboardModifiers.md" +import KeyEvent from "../../collections/structs/KeyEvent.md" +import Point from "../../collections/structs/Point.md" +import PointerEvent from "../../collections/structs/PointerEvent.md" +import PointerScrollEvent from "../../collections/structs/PointerScrollEvent.md" +import StandardListViewItem from "../../collections/structs/StandardListViewItem.md" +import TableColumn from "../../collections/structs/TableColumn.md" + +import AccessibleRole from "../../collections/enums/AccessibleRole.md" +import AnimationDirection from "../../collections/enums/AnimationDirection.md" +import ColorScheme from "../../collections/enums/ColorScheme.md" +import DialogButtonRole from "../../collections/enums/DialogButtonRole.md" +import EventResult from "../../collections/enums/EventResult.md" +import FillRule from "../../collections/enums/FillRule.md" +import ImageFit from "../../collections/enums/ImageFit.md" +import ImageHorizontalAlignment from "../../collections/enums/ImageHorizontalAlignment.md" +import ImageRendering from "../../collections/enums/ImageRendering.md" +import ImageTiling from "../../collections/enums/ImageTiling.md" +import ImageVerticalAlignment from "../../collections/enums/ImageVerticalAlignment.md" +import InputType from "../../collections/enums/InputType.md" +import LayoutAlignment from "../../collections/enums/LayoutAlignment.md" +import MouseCursor from "../../collections/enums/MouseCursor.md" +import Orientation from "../../collections/enums/Orientation.md" +import PathEvent from "../../collections/enums/PathEvent.md" +import PointerEventButton from "../../collections/enums/PointerEventButton.md" +import PointerEventKind from "../../collections/enums/PointerEventKind.md" +import PopupClosePolicy from "../../collections/enums/PopupClosePolicy.md" +import ScrollBarPolicy from "../../collections/enums/ScrollBarPolicy.md" +import SortOrder from "../../collections/enums/SortOrder.md" +import StandardButtonKind from "../../collections/enums/StandardButtonKind.md" +import TextHorizontalAlignment from "../../collections/enums/TextHorizontalAlignment.md" +import TextOverflow from "../../collections/enums/TextOverflow.md" +import TextStrokeStyle from "../../collections/enums/TextStrokeStyle.md" +import TextVerticalAlignment from "../../collections/enums/TextVerticalAlignment.md" +import TextWrap from "../../collections/enums/TextWrap.md" + + +## Structs + +### FontMetrics + + +### KeyboardModifiers + + +### KeyEvent + + +### Point + + +### PointerEvent + + +### PointerScrollEvent + + +### StandardListViewItem + + +### TableColumn + + +## Enums + +### AccessibleRole + + +### AnimationDirection + + +### ColorScheme + + +### DialogButtonRole + + +### EventResult + + +### FillRule + + +### ImageFit + + +### ImageHorizontalAlignment + + +### ImageRendering + + +### ImageTiling + + +### ImageVerticalAlignment + + +### InputType + + +### LayoutAlignment + + +### MouseCursor + + +### Orientation + + +### PathEvent + + +### PointerEventButton + + +### PointerEventKind + + +### PopupClosePolicy + + +### ScrollBarPolicy + + +### SortOrder + + +### StandardButtonKind + + +### TextHorizontalAlignment + + +### TextOverflow + + +### TextStrokeStyle + + +### TextVerticalAlignment + + +### TextWrap + diff --git a/docs/astro/src/utils/link-data.json b/docs/astro/src/utils/link-data.json index 2195cba25..cc38f3aee 100644 --- a/docs/astro/src/utils/link-data.json +++ b/docs/astro/src/utils/link-data.json @@ -3,7 +3,7 @@ "href": "/reference/primitive-types#animation" }, "AnimationTick": { - "href": "/reference/global-functions-enums/builtinfunctions/#animation-tick---duration" + "href": "/reference/global-functions/builtinfunctions/#animation-tick---duration" }, "angle": { "href": "/reference/primitive-types#angle" @@ -33,7 +33,7 @@ "href": "/reference/primitive-types#duration" }, "DebugFn": { - "href": "/reference/global-functions-enums/builtinfunctions#debug" + "href": "/reference/global-functions/builtinfunctions#debug" }, "easing": { "href": "/reference/primitive-types#easing" @@ -105,6 +105,9 @@ "physicalLength": { "href": "/reference/primitive-types#physical-length" }, + "PopupWindow": { + "href": "/reference/window/popupwindow" + }, "ProgressIndicator": { "href": "/reference/std-widgets/progressindicator" }, @@ -159,6 +162,9 @@ "QtBackend": { "href": "/guide/backends-and-renderers/backend_qt" }, + "Window": { + "href": "/reference/window/window" + }, "WinitBackend": { "href": "/guide/backends-and-renderers/backend_winit/" }