from typing import Optional

from flet.controls.base_control import control
from flet.controls.control import Control
from flet.controls.control_event import ControlEventHandler
from flet.controls.material.badge import BadgeValue
from flet.controls.types import Number

__all__ = ["Semantics"]


@control("Semantics")
class Semantics(Control):
    """
    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.
    """

    content: Optional[Control] = None
    """
    The Control to annotate.
    """

    label: Optional[str] = None
    """
    A textual description of the [`content`][flet.Semantics.content].
    """

    expanded: Optional[bool] = None
    """
    Whether this subtree represents something that can be in an "expanded" or
    "collapsed" state.
    """

    hidden: Optional[bool] = None
    """
    Whether this subtree is currently hidden.
    """

    selected: Optional[bool] = None
    """
    Whether this subtree represents something that can be in a selected or unselected
    state, and what its current state is.
    """

    button: Optional[bool] = None
    """
    Whether this subtree represents a button.
    """

    obscured: Optional[bool] = None
    """
    Whether [`value`][flet.Semantics.value] should be obscured.
    """

    multiline: Optional[bool] = None
    """
    Whether the [`value`][flet.Semantics.value] is coming from a field that supports multiline text editing.
    """

    focusable: Optional[bool] = None
    """
    Whether the node is able to hold input focus.
    """

    read_only: Optional[bool] = None
    """
    Whether this subtree is read only.
    """

    focus: Optional[bool] = None
    """
    Whether the node currently holds input focus.
    """

    slider: Optional[bool] = None
    """
    Whether this subtree represents a slider.
    """

    tooltip: Optional[str] = None
    """
    A textual description of the widget's tooltip.
    """

    badge: Optional[BadgeValue] = None
    """
    TBD
    """

    toggled: Optional[bool] = None
    """
    Whether this subtree represents a toggle switch or similar widget with an "on"
    state, and what its current state is.
    """

    max_value_length: Optional[Number] = None
    """
    The maximum number of characters that can be entered into an editable text field.
    """

    checked: Optional[bool] = None
    """
    Whether this subtree represents a checkbox or similar widget with a "checked"
    state, and what its current state is.
    """

    value: Optional[str] = None
    """
    A textual description of the `value` of the `content` control.
    """

    increased_value: Optional[str] = None
    """
    The value that the semantics node represents when it is increased.
    """

    decreased_value: Optional[str] = None
    """
    The value that the semantics node represents when it is decreased.
    """

    hint_text: Optional[str] = None
    """
    A brief textual description of the result of an action performed on the `content`
    control.
    """

    on_tap_hint_text: Optional[str] = None
    """
    TBD
    """

    current_value_length: Optional[int] = None
    """
    The current number of characters that have been entered into an editable text
    field.
    """

    heading_level: Optional[int] = None
    """
    The heading level in the DOM document structure.
    """

    exclude_semantics: bool = False
    """
    TBD
    """

    mixed: Optional[bool] = 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.
    """

    on_long_press_hint_text: Optional[str] = None
    """
    TBD
    """

    container: Optional[bool] = None
    """
    TBD
    """

    live_region: Optional[bool] = None
    """
    Whether this subtree should be considered a live region.
    """

    textfield: Optional[bool] = None
    """
    Whether  this subtree represents a text field.
    """

    link: Optional[bool] = None
    """
    Whether this subtree represents a link.
    """

    header: Optional[bool] = None
    """
    Whether this subtree represents a header.
    """

    image: Optional[bool] = None
    """
    Whether the node represents an image.
    """

    on_tap: Optional[ControlEventHandler["Semantics"]] = None
    """
    Called when this control is tapped.
    """

    on_double_tap: Optional[ControlEventHandler["Semantics"]] = None
    """
    TBD
    """

    on_increase: Optional[ControlEventHandler["Semantics"]] = None
    """
    Called when the value represented by the semantics node is increased.
    """

    on_decrease: Optional[ControlEventHandler["Semantics"]] = None
    """
    Called when the value represented by the semantics node is decreased.
    """

    on_dismiss: Optional[ControlEventHandler["Semantics"]] = None
    """
    Called when the node is dismissed.
    """

    on_scroll_left: Optional[ControlEventHandler["Semantics"]] = None
    """
    Called when a user moves their finger across the screen from right to left.
    """

    on_scroll_right: Optional[ControlEventHandler["Semantics"]] = None
    """
    Called when a user moves their finger across the screen from left to right.
    """

    on_scroll_up: Optional[ControlEventHandler["Semantics"]] = None
    """
    Called when a user moves their finger across the screen from bottom to top.
    """

    on_scroll_down: Optional[ControlEventHandler["Semantics"]] = None
    """
    Called when a user moves their finger across the screen from top to bottom.
    """

    on_copy: Optional[ControlEventHandler["Semantics"]] = None
    """
    Called when the current selection is copied to the clipboard.
    """

    on_cut: Optional[ControlEventHandler["Semantics"]] = None
    """
    Called when the current selection is cut to the clipboard.
    """

    on_paste: Optional[ControlEventHandler["Semantics"]] = None
    """
    Called when the current content of the clipboard is pasted.
    """

    on_long_press: Optional[ControlEventHandler["Semantics"]] = None
    """
    Called when the node is long-pressed (pressing and holding the screen with the
    finger for a few seconds without moving it).
    """

    on_move_cursor_forward_by_character: Optional[ControlEventHandler["Semantics"]] = (
        None
    )
    """
    Called when the cursor is moved forward by one character.
    """

    on_move_cursor_backward_by_character: Optional[ControlEventHandler["Semantics"]] = (
        None
    )
    """
    Called when the cursor is moved backward by one character.
    """

    on_did_gain_accessibility_focus: Optional[ControlEventHandler["Semantics"]] = None
    """
    Called when the node has gained accessibility focus.
    """

    on_did_lose_accessibility_focus: Optional[ControlEventHandler["Semantics"]] = None
    """
    Called when the node has lost accessibility focus.
    """

    on_set_text: Optional[ControlEventHandler["Semantics"]] = 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.
    """