Semantics

Provides semantic annotations for the control tree, describing the meaning and purpose of controls.

These annotations are utilized by accessibility tools, search engines, and semantic analysis software to better understand the structure and functionality of the application.

Inherits: Control

Properties

• badge - TBD
• button - Whether this subtree represents a button.
• checked - Whether this subtree represents a checkbox or similar widget with a "checked" state, and what its current state is.
• container - Whether this semantics node should introduce its own semantic container.
• content - The Control to annotate.
• current_value_length - The current number of characters that have been entered into an editable text field.
• decreased_value - The value that the semantics node represents when it is decreased.
• exclude_semantics - Whether the semantics information from content should be excluded.
• expanded - Whether this subtree represents something that can be in an "expanded" or "collapsed" state.
• focus - Whether the node currently holds input focus.
• focusable - Whether the node is able to hold input focus.
• header - Whether this subtree represents a header.
• heading_level - The heading level in the DOM document structure.
• hidden - Whether this subtree is currently hidden.
• hint_text - A brief textual description of the result of an action performed on the content control.
• image - Whether the node represents an image.
• increased_value - The value that the semantics node represents when it is increased.
• label - A textual description of the content.
• link - Whether this subtree represents a link.
• live_region - Whether this subtree should be considered a live region.
• max_value_length - The maximum number of characters that can be entered into an editable text field.
• mixed - Whether this subtree represents a checkbox or similar control with a "half-checked" state or similar, and whether it is currently in this half-checked state.
• multiline - Whether the value is coming from a field that supports multiline text editing.
• obscured - Whether value should be obscured.
• read_only - Whether this subtree is read only.
• selected - Whether this subtree represents something that can be in a selected or unselected state, and what its current state is.
• slider - Whether this subtree represents a slider.
• textfield - Whether this subtree represents a text field.
• toggled - Whether this subtree represents a toggle switch or similar widget with an "on" state, and what its current state is.
• tooltip - A textual description of the widget's tooltip.
• value - A textual description of the value of the content control.

Events

• on_copy - Called when the current selection is copied to the clipboard.
• on_cut - Called when the current selection is cut to the clipboard.
• on_decrease - Called when the value represented by the semantics node is decreased.
• on_did_gain_accessibility_focus - Called when the node has gained accessibility focus.
• on_did_lose_accessibility_focus - Called when the node has lost accessibility focus.
• on_dismiss - Called when the node is dismissed.
• on_double_tap - Reserved for a semantic double-tap action.
• on_increase - Called when the value represented by the semantics node is increased.
• on_long_press - Called when the node is long-pressed (pressing and holding the screen with the finger for a few seconds without moving it).
• on_long_press_hint_text - A hint describing what happens when the user activates on_long_press.
• on_move_cursor_backward_by_character - Called when the cursor is moved backward by one character.
• on_move_cursor_forward_by_character - Called when the cursor is moved forward by one character.
• on_paste - Called when the current content of the clipboard is pasted.
• on_scroll_down - Called when a user moves their finger across the screen from top to bottom.
• on_scroll_left - Called when a user moves their finger across the screen from right to left.
• on_scroll_right - Called when a user moves their finger across the screen from left to right.
• on_scroll_up - Called when a user moves their finger across the screen from bottom to top.
• on_set_text - Called when a user wants to replace the current text in the text field with a new text.
• on_tap - Called when this control is tapped.
• on_tap_hint_text - A hint describing what happens when the user activates on_tap.

Examples

Semantics

play_arrowTry Online

import flet as ft


def main(page: ft.Page):
    def handle_gain_accessibility_focus(e: ft.Event[ft.Semantics]):
        print("focus gained")

    def handle_lose_accessibility_focus(e: ft.Event[ft.Semantics]):
        print("focus lost")

    page.add(
        ft.SafeArea(
            content=ft.Column(
                controls=[
                    ft.Semantics(
                        label="Input your occupation",
                        on_did_gain_accessibility_focus=handle_gain_accessibility_focus,
                        on_did_lose_accessibility_focus=handle_lose_accessibility_focus,
                        content=ft.TextField(
                            label="Occupation",
                            hint_text="Use 20 words or less",
                            value="What is your occupation?",
                        ),
                    ),
                    ft.Icon(ft.Icons.SETTINGS, color="#c1c1c1"),
                ]
            ),
        )
    )


if __name__ == "__main__":
    ft.run(main)

Properties

buildbadgeclass-attributeinstance-attribute

badge: BadgeValue | None = None

TBD

buildbuttonclass-attributeinstance-attribute

button: bool | None = None

Whether this subtree represents a button.

buildcheckedclass-attributeinstance-attribute

checked: bool | None = None

Whether this subtree represents a checkbox or similar widget with a "checked" state, and what its current state is.

buildcontainerclass-attributeinstance-attribute

container: bool | None = None

Whether this semantics node should introduce its own semantic container.

A container groups the semantics of its subtree into a distinct node instead of always merging with surrounding semantics.

buildcontentclass-attributeinstance-attribute

content: Control | None = None

The Control to annotate.

buildcurrent_value_lengthclass-attributeinstance-attribute

current_value_length: int | None = None

The current number of characters that have been entered into an editable text field.

builddecreased_valueclass-attributeinstance-attribute

decreased_value: str | None = None

The value that the semantics node represents when it is decreased.

buildexclude_semanticsclass-attributeinstance-attribute

exclude_semantics: bool = False

Whether the semantics information from content should be excluded.

When True, only the semantics configured on this Semantics wrapper are exposed.

buildexpandedclass-attributeinstance-attribute

expanded: bool | None = None

Whether this subtree represents something that can be in an "expanded" or "collapsed" state.

buildfocusclass-attributeinstance-attribute

focus: bool | None = None

Whether the node currently holds input focus.

buildfocusableclass-attributeinstance-attribute

focusable: bool | None = None

Whether the node is able to hold input focus.

buildheaderclass-attributeinstance-attribute

header: bool | None = None

Whether this subtree represents a header.

buildheading_levelclass-attributeinstance-attribute

heading_level: int | None = None

The heading level in the DOM document structure.

buildhiddenclass-attributeinstance-attribute

hidden: bool | None = None

Whether this subtree is currently hidden.

buildhint_textclass-attributeinstance-attribute

hint_text: str | None = None

A brief textual description of the result of an action performed on the content control.

buildimageclass-attributeinstance-attribute

image: bool | None = None

Whether the node represents an image.

buildincreased_valueclass-attributeinstance-attribute

increased_value: str | None = None

The value that the semantics node represents when it is increased.

buildlabelclass-attributeinstance-attribute

label: str | None = None

A textual description of the content.

buildlinkclass-attributeinstance-attribute

link: bool | None = None

Whether this subtree represents a link.

buildlive_regionclass-attributeinstance-attribute

live_region: bool | None = None

Whether this subtree should be considered a live region.

buildmax_value_lengthclass-attributeinstance-attribute

max_value_length: Number | None = None

The maximum number of characters that can be entered into an editable text field.

buildmixedclass-attributeinstance-attribute

mixed: bool | None = None

Whether this subtree represents a checkbox or similar control with a "half-checked" state or similar, and whether it is currently in this half-checked state.

buildmultilineclass-attributeinstance-attribute

multiline: bool | None = None

Whether the value is coming from a field that supports multiline text editing.

buildobscuredclass-attributeinstance-attribute

obscured: bool | None = None

Whether value should be obscured.

buildread_onlyclass-attributeinstance-attribute

read_only: bool | None = None

Whether this subtree is read only.

buildselectedclass-attributeinstance-attribute

selected: bool | None = None

Whether this subtree represents something that can be in a selected or unselected state, and what its current state is.

buildsliderclass-attributeinstance-attribute

slider: bool | None = None

Whether this subtree represents a slider.

buildtextfieldclass-attributeinstance-attribute

textfield: bool | None = None

Whether this subtree represents a text field.

buildtoggledclass-attributeinstance-attribute

toggled: bool | None = None

Whether this subtree represents a toggle switch or similar widget with an "on" state, and what its current state is.

buildtooltipclass-attributeinstance-attribute

tooltip: str | None = None

A textual description of the widget's tooltip.

buildvalueclass-attributeinstance-attribute

value: str | None = None

A textual description of the value of the content control.

Events

bolton_copyclass-attributeinstance-attribute

on_copy: ControlEventHandler[Semantics] | None = None

Called when the current selection is copied to the clipboard.

bolton_cutclass-attributeinstance-attribute

on_cut: ControlEventHandler[Semantics] | None = None

Called when the current selection is cut to the clipboard.

bolton_decreaseclass-attributeinstance-attribute

on_decrease: ControlEventHandler[Semantics] | None = None

Called when the value represented by the semantics node is decreased.

bolton_did_gain_accessibility_focusclass-attributeinstance-attribute

on_did_gain_accessibility_focus: (
    ControlEventHandler[Semantics] | None
) = None

Called when the node has gained accessibility focus.

bolton_did_lose_accessibility_focusclass-attributeinstance-attribute

on_did_lose_accessibility_focus: (
    ControlEventHandler[Semantics] | None
) = None

Called when the node has lost accessibility focus.

bolton_dismissclass-attributeinstance-attribute

on_dismiss: ControlEventHandler[Semantics] | None = None

Called when the node is dismissed.

bolton_double_tapclass-attributeinstance-attribute

on_double_tap: ControlEventHandler[Semantics] | None = None

Reserved for a semantic double-tap action.

Warning

This event is not wired by the current runtime implementation and will not fire until the control implementation adds support for it.

bolton_increaseclass-attributeinstance-attribute

on_increase: ControlEventHandler[Semantics] | None = None

Called when the value represented by the semantics node is increased.

bolton_long_pressclass-attributeinstance-attribute

on_long_press: ControlEventHandler[Semantics] | None = None

Called when the node is long-pressed (pressing and holding the screen with the finger for a few seconds without moving it).

bolton_long_press_hint_textclass-attributeinstance-attribute

on_long_press_hint_text: str | None = None

A hint describing what happens when the user activates on_long_press.

bolton_move_cursor_backward_by_characterclass-attributeinstance-attribute

on_move_cursor_backward_by_character: (
    ControlEventHandler[Semantics] | None
) = None

Called when the cursor is moved backward by one character.

bolton_move_cursor_forward_by_characterclass-attributeinstance-attribute

on_move_cursor_forward_by_character: (
    ControlEventHandler[Semantics] | None
) = None

Called when the cursor is moved forward by one character.

bolton_pasteclass-attributeinstance-attribute

on_paste: ControlEventHandler[Semantics] | None = None

Called when the current content of the clipboard is pasted.

bolton_scroll_downclass-attributeinstance-attribute

on_scroll_down: ControlEventHandler[Semantics] | None = None

Called when a user moves their finger across the screen from top to bottom.

bolton_scroll_leftclass-attributeinstance-attribute

on_scroll_left: ControlEventHandler[Semantics] | None = None

Called when a user moves their finger across the screen from right to left.

bolton_scroll_rightclass-attributeinstance-attribute

on_scroll_right: ControlEventHandler[Semantics] | None = (
    None
)

Called when a user moves their finger across the screen from left to right.

bolton_scroll_upclass-attributeinstance-attribute

on_scroll_up: ControlEventHandler[Semantics] | None = None

Called when a user moves their finger across the screen from bottom to top.

bolton_set_textclass-attributeinstance-attribute

on_set_text: ControlEventHandler[Semantics] | None = None

Called when a user wants to replace the current text in the text field with a new text.

Voice access users can trigger this handler by speaking type <text> to their Android devices.

bolton_tapclass-attributeinstance-attribute

on_tap: ControlEventHandler[Semantics] | None = None

Called when this control is tapped.

bolton_tap_hint_textclass-attributeinstance-attribute

on_tap_hint_text: str | None = None

A hint describing what happens when the user activates on_tap.

Assistive technologies can announce this together with hint_text to make the tap action more specific.