Common Properties & Callbacks
The Slint elements have many common properties, callbacks and behavior. This page describes these properties and their usage.
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
length default: 0px
The position of the element relative to its parent.
z
float default: 0.0
Allows to specify a different order to stack the items with its siblings. The value must be a compile time constant.
width, height
length default: 0px
The width and height of the element. When set, this overrides the default size.
opacity
float default: 1
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.
visible
bool default: true
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.
absolute-position
struct Point (out)
default: a struct with all default values
Point
This structure represents a point with x and y coordinate
x
(length):y
(length):
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 Window or 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).
Miscellaneous
cache-rendering-hint
bool default: false
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
enum DialogButtonRole default: none
DialogButtonRole
This enum represents the value of the dialog-button-role
property which can be added to
any element within a Dialog
to put that item in the button row, and its exact position
depends on the role and the platform.
none
: This isn’t a button meant to go into the bottom rowaccept
: This is the role of the main button to click to accept the dialog. e.g. “Ok” or “Yes”reject
: This is the role of the main button to click to reject the dialog. e.g. “Cancel” or “No”apply
: This is the role of the “Apply” buttonreset
: This is the role of the “Reset” buttonhelp
: This is the role of the “Help” buttonaction
: This is the role of any other button that performs another action.
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
invocation is from inside to outside. The following example will print “first”, then “second”, and then “third”:
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 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.
accessible-role
enum AccessibleRole default: the first enum value
AccessibleRole
This enum represents the different values for the accessible-role
property, used to describe the
role of an element in the context of assistive technology such as screen readers.
none
: The element isn’t accessible.button
: The element is aButton
or behaves like one.checkbox
: The element is aCheckBox
or behaves like one.combobox
: The element is aComboBox
or behaves like one.list
: The element is aListView
or behaves like one.slider
: The element is aSlider
or behaves like one.spinbox
: The element is aSpinBox
or behaves like one.tab
: The element is aTab
or behaves like one.tab-list
: The element is similar to the tab bar in aTabWidget
.text
: The role for aText
element. It’s automatically applied.table
: The role for aTableView
or behaves like one.tree
: The role for a TreeView or behaves like one. (Not provided yet)progress-indicator
: The element is aProgressIndicator
or behaves like one.text-input
: The role for widget with editable text such as aLineEdit
or aTextEdit
switch
: The element is aSwitch
or behaves like one.list-item
: The element is an item in aListView
.
The role of the element. This property is mandatory to be able to use any other accessible properties. It should be set to a constant value. (default value: none
for most elements, but text
for the Text element)
accessible-checkable
bool default: false
Whether the element is can be checked or not.
accessible-checked
bool default: false
Whether the element is checked or not. This maps to the “checked” state of checkboxes, radio buttons, and other widgets.
accessible-description
string default: ""
The description for the current element.
accessible-enabled
bool default: false
Whether the element is enabled or not. This maps to the “enabled” state of most widgets. (default value: true
)
accessible-label
string default: ""
The label for an interactive element. (default value: empty for most elements, or the value of the text
property for Text elements)
accessible-value-maximum
float default: 0.0
The maximum value of the item. This is used for example by spin boxes.
accessible-value-minimum
float default: 0.0
The minimum value of the item.
accessible-value-step
float default: 0.0
The smallest increment or decrement by which the current value can change. This corresponds to the step by which a handle on a slider can be dragged.
accessible-value
string default: ""
The current value of the item.
accessible-placeholder-text
string default: ""
A placeholder text to use when the item’s value is empty. Applies to text elements.
accessible-item-selectable
bool default: false
Whether the element can be selected or not.
accessible-item-selected
bool default: false
Whether the element is selected or not. This maps to the “is-selected” state of listview items.
accessible-item-index
int default: 0
The index (starting from 0) of this element in a group of similar elements. Applies to list items, radio buttons and other elements.
accessible-item-count
int default: 0
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.
© 2024 SixtyFPS GmbH