Skip to content

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(BadgeValue | None) –

    TBD

  • button(bool | None) –

    Whether this subtree represents a button.

  • checked(bool | None) –

    Whether this subtree represents a checkbox or similar widget with a "checked"

  • container(bool | None) –

    TBD

  • content(Control | None) –

    The Control to annotate.

  • current_value_length(int | None) –

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

  • decreased_value(str | None) –

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

  • exclude_semantics(bool) –

    TBD

  • expanded(bool | None) –

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

  • focus(bool | None) –

    Whether the node currently holds input focus.

  • focusable(bool | None) –

    Whether the node is able to hold input focus.

  • header(bool | None) –

    Whether this subtree represents a header.

  • heading_level(int | None) –

    The heading level in the DOM document structure.

  • hidden(bool | None) –

    Whether this subtree is currently hidden.

  • hint_text(str | None) –

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

  • image(bool | None) –

    Whether the node represents an image.

  • increased_value(str | None) –

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

  • label(str | None) –

    A textual description of the content.

  • link(bool | None) –

    Whether this subtree represents a link.

  • live_region(bool | None) –

    Whether this subtree should be considered a live region.

  • max_value_length(Number | None) –

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

  • mixed(bool | None) –

    Whether this subtree represents a checkbox or similar control with a "half-checked"

  • multiline(bool | None) –

    Whether the value is coming from a field that supports multiline

  • obscured(bool | None) –

    Whether value should be obscured.

  • read_only(bool | None) –

    Whether this subtree is read only.

  • selected(bool | None) –

    Whether this subtree represents something that can be in a selected or unselected

  • slider(bool | None) –

    Whether this subtree represents a slider.

  • textfield(bool | None) –

    Whether this subtree represents a text field.

  • toggled(bool | None) –

    Whether this subtree represents a toggle switch or similar widget with an "on"

  • tooltip(str | None) –

    A textual description of the widget's tooltip.

  • value(str | None) –

    A textual description of the value of the content control.

Events

Examples#

Basic Example#

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.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"),
            ]
        )
    )


ft.run(main)

Properties#

badge #

badge: BadgeValue | None = None

TBD

button #

button: bool | None = None

Whether this subtree represents a button.

checked #

checked: bool | None = None

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

container #

container: bool | None = None

TBD

content #

content: Control | None = None

The Control to annotate.

current_value_length #

current_value_length: int | None = None

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

decreased_value #

decreased_value: str | None = None

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

exclude_semantics #

exclude_semantics: bool = False

TBD

expanded #

expanded: bool | None = None

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

focus #

focus: bool | None = None

Whether the node currently holds input focus.

focusable #

focusable: bool | None = None

Whether the node is able to hold input focus.

header #

header: bool | None = None

Whether this subtree represents a header.

heading_level #

heading_level: int | None = None

The heading level in the DOM document structure.

hidden #

hidden: bool | None = None

Whether this subtree is currently hidden.

hint_text #

hint_text: str | None = None

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

image #

image: bool | None = None

Whether the node represents an image.

increased_value #

increased_value: str | None = None

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

label #

label: str | None = None

A textual description of the content.

link: bool | None = None

Whether this subtree represents a link.

live_region #

live_region: bool | None = None

Whether this subtree should be considered a live region.

max_value_length #

max_value_length: Number | None = None

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

mixed #

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.

multiline #

multiline: bool | None = None

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

obscured #

obscured: bool | None = None

Whether value should be obscured.

read_only #

read_only: bool | None = None

Whether this subtree is read only.

selected #

selected: bool | None = None

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

slider #

slider: bool | None = None

Whether this subtree represents a slider.

textfield #

textfield: bool | None = None

Whether this subtree represents a text field.

toggled #

toggled: bool | None = None

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

tooltip #

tooltip: str | None = None

A textual description of the widget's tooltip.

value #

value: str | None = None

A textual description of the value of the content control.

Events#

on_copy #

on_copy: ControlEventHandler[Semantics] | None = None

Called when the current selection is copied to the clipboard.

on_cut #

on_cut: ControlEventHandler[Semantics] | None = None

Called when the current selection is cut to the clipboard.

on_decrease #

on_decrease: ControlEventHandler[Semantics] | None = None

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

on_did_gain_accessibility_focus #

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

Called when the node has gained accessibility focus.

on_did_lose_accessibility_focus #

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

Called when the node has lost accessibility focus.

on_dismiss #

on_dismiss: ControlEventHandler[Semantics] | None = None

Called when the node is dismissed.

on_double_tap #

on_double_tap: ControlEventHandler[Semantics] | None = None

TBD

on_increase #

on_increase: ControlEventHandler[Semantics] | None = None

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

on_long_press #

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).

on_long_press_hint_text #

on_long_press_hint_text: str | None = None

TBD

on_move_cursor_backward_by_character #

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

Called when the cursor is moved backward by one character.

on_move_cursor_forward_by_character #

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

Called when the cursor is moved forward by one character.

on_paste #

on_paste: ControlEventHandler[Semantics] | None = None

Called when the current content of the clipboard is pasted.

on_scroll_down #

on_scroll_down: ControlEventHandler[Semantics] | None = None

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

on_scroll_left #

on_scroll_left: ControlEventHandler[Semantics] | None = None

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

on_scroll_right #

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

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

on_scroll_up #

on_scroll_up: ControlEventHandler[Semantics] | None = None

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

on_set_text #

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.

on_tap #

on_tap: ControlEventHandler[Semantics] | None = None

Called when this control is tapped.

on_tap_hint_text #

on_tap_hint_text: str | None = None

TBD