export component Example inherits Window {    width: 100px;    height: 100px;    forward-focus: my-key-handler;    my-key-handler := FocusScope {        key-pressed(event) => {            debug(event.text);            if (event.modifiers.control) {                debug("control was pressed during this event");            }            if (event.text == Key.Escape) {                debug("Esc key was pressed")            }        accept        }
        KeyBinding {            keys: @keys(Control + X);            activated => {                debug("Control + X pressed")            }        }    }}

FocusScope 可以使用 KeyBinding 元素来响应 键盘快捷键，并暴露用于手动处理按键事件的回调。 请注意，FocusScope 仅在它 has-focus 或它包含另一个 has-focus 的 FocusScope 时才会处理按键事件（参见 按键事件传递）

KeyEvent 具有一个 text 属性，它是被按下的键对应的字符。 当按下不可打印键时，该字符将是一个控制字符， 或者会被映射到一个私有 Unicode 字符。这些不可打印的特殊字符的映射可在 KeyEvent 命名空间中找到

按键事件传递

按键事件被传递给 has-focus 的元素。

在尝试传递 KeyEvent 之前，会检查是否有其他元素想要拦截该 KeyEvent。 从 Window 开始向下遍历所有元素，朝着获得焦点的元素，会调用 capture_key_pressed 或 capture_key_released。 如果其中任何一个返回 EventResult::accept，则按键事件处理在此停止。如果返回 EventResult::reject， 则事件继续传递。

如果没有元素捕获该 KeyEvent，则通过调用 key-pressed 或 key-released 将 KeyEvent 传递给获得焦点的元素。 如果这些回调返回 EventResult::accept，则事件传递结束，并且该事件已被处理。否则，（递归地）尝试 将按键事件传递给父元素。

属性

has-focus

bool (out) default: false

当该元素具有键盘焦点时为 true。

enabled

bool default: true

当为 false 时，FocusScope 将不接受焦点，无论是通过单击、Tab 焦点遍历还是通过代码设置。

父 FocusScope 仍会接收来自其子 FocusScope 被拒绝的按键事件，即使 enabled 被设置为 false。

focus-on-click

bool default: true

当为 true 时，FocusScope 在被单击时会将自己设置为获得焦点的元素。

如果 enabled 属性被设置为 false，则此属性无效。

focus-on-tab-navigation

bool default: true

当为 true 时，FocusScope 将作为 Tab 焦点遍历的一部分接受焦点。

如果 enabled 属性被设置为 false，则此属性无效。

函数

focus()

调用此函数将键盘焦点转移到此 FocusScope，以便接收将来的 KeyEvent。

clear-focus()

调用此函数可以从当前具有焦点的 FocusScope 移除键盘焦点。另请参阅 焦点处理。

回调

capture-key-pressed(event: KeyEvent) -> EventResult

此函数在按键事件处理期间被调用，在调用 key-pressed 之前。使用它来拦截按键按下事件。返回的 EventResult 指示是接受还是拒绝该事件。被拒绝的事件将被转发给父元素。

capture-key-released(event: KeyEvent) -> EventResult

此函数在按键事件处理期间被调用，在调用 key-released 之前。使用它来拦截按键释放事件。返回的 EventResult 指示是接受还是拒绝该事件。被拒绝的事件将被转发给父元素。

key-pressed(event: KeyEvent) -> EventResult

在按键被按下时调用，参数是一个 KeyEvent 结构体。返回的 EventResult 指示是接受还是拒绝该事件。被拒绝的事件将被转发给父元素。

key-released(event: KeyEvent) -> EventResult

在按键被释放时调用，参数是一个 KeyEvent 结构体。返回的 EventResult 指示是接受还是拒绝该事件。被拒绝的事件将被转发给父元素。

focus-changed-event(reason: FocusReason)

当 FocusScope 上的焦点发生变化时调用。参数是一个 FocusReason 枚举，其中包含焦点变化的原因。

focus-gained(reason: FocusReason)

当 FocusScope 获得焦点时调用。参数是一个 FocusReason 枚举，其中包含获得焦点的原因。

focus-lost(reason: FocusReason)

当 FocusScope 失去焦点时调用。参数是一个 FocusReason 枚举，其中包含失去焦点的原因。

KeyBinding

将 KeyBinding 元素放置在 FocusScope 内以声明键盘快捷键。 KeyBinding 使用 逻辑键，基于按键产生的字符，而不是物理按键位置。

有关详细信息，请参阅 键绑定。

KeyBinding 的属性

keys

keys default: @keys()

要与传入的按键事件匹配的 keys。

enabled

bool default: true

此 KeyBinding 当前是否启用。已禁用的 KeyBinding 元素不会消耗按键事件，也永远不会调用它们的 activated() 回调。

KeyBinding 的回调

activated()

当父 FocusScope 接收到与此 KeyBinding 的 keys 匹配的按键事件时调用。