---
title: FocusScope
description: FocusScope element api.
---
import SlintProperty from '@slint/common-files/src/components/SlintProperty.astro';
import Link from '@slint/common-files/src/components/Link.astro';

```slint playground
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")
            }
        }
    }
}
```

The `FocusScope` can react to <Link type="KeyBindingOverview" label="keyboard shortcuts"/> using the <Link type="KeyBinding" label="KeyBinding element"/>, and exposes callbacks to handle key events manually.
Note that `FocusScope` will only handle key events when it either `has-focus`, or when it surrounds another FocusScope that `has-focus` (see [Key Event Delivery](#key-event-delivery))

The <Link type="KeyEvent" /> has a text property, which is a character of the key entered.
When a non-printable key is pressed, the character will be either a control character,
or it will be mapped to a private unicode character. The mapping of these non-printable, special characters is available in the <Link type="KeyEvent"/> namespace

## Key Event Delivery

Key events are delivered to the element that `has-focus`.

Before attempting to deliver the `KeyEvent`, it is checked whether some other element wants to intercept the `KeyEvent`.
Visiting all the elements starting at the Window, going down toward the focused element, `capture_key_pressed` or `capture_key_released` is called.
If any of these returns `EventResult::accept`, then key event processing stops at this point. If `EventResult::reject` is returned,
then event delivery continues.

If no element captures the `KeyEvent`, then the `KeyEvent` is delivered to the focused element by calling `key-pressed` or `key-released`.
If these callbacks return `EventResult::accept`, then event delivery is finished and the event has been handled. Otherwise, (recursively) try
to deliver the key event to the parent element.

## Properties

### has-focus
<SlintProperty propName="has-focus" typeName="bool" defaultValue="false" propertyVisibility="out">
Is `true` when the element has keyboard focus.
</SlintProperty>

### enabled
<SlintProperty propName="enabled" typeName="bool" defaultValue="true">
When false, the FocusScope will not accept focus, neither via click nor via tab focus traversal, not even programmatically.

A parent `FocusScope` will still receive key events from child `FocusScope`s that were rejected, even if `enabled` is set to false.
</SlintProperty>

### focus-on-click
<SlintProperty propName="focus-on-click" typeName="bool" defaultValue="true">
When true, the `FocusScope` will make itself the focused element when clicked.

This property has no effect if the `enabled` property is set to false.
</SlintProperty>

### focus-on-tab-navigation
<SlintProperty propName="focus-on-tab-navigation" typeName="bool" defaultValue="true">
When true, the `FocusScope` will accept focus as part of the tab focus traversal.

This property has no effect if the `enabled` property is set to false.
</SlintProperty>

## Functions

### focus()
Call this function to transfer keyboard focus to this `FocusScope`, to receive future <Link type="KeyEvent" />s.

### clear-focus()
Call this function to remove keyboard focus from this `FocusScope` if it currently has the focus. See also <Link type="FocusHandling" />.

## Callbacks

### capture-key-pressed(KeyEvent) -> EventResult
This function is called during key event handling, *before* `key-pressed` is called. Use this to intercept key press events. The returned <Link type="EventResult" />
indicates whether to accept or reject the event. Rejected events are forwarded to the parent element.

### capture-key-released(KeyEvent) -> EventResult
This function is called during key event handling, *before* `key-released` is called. Use this to intercept key release events. The returned <Link type="EventResult" />
indicates whether to accept or reject the event. Rejected events are forwarded to the parent element.

### key-pressed(KeyEvent) -> EventResult
Invoked when a key is pressed, the argument is a <Link type="KeyEvent" /> struct. The returned <Link type="EventResult" />
indicates whether to accept or reject the event. Rejected events are forwarded to the parent element.

### key-released(KeyEvent) -> EventResult
Invoked when a key is released, the argument is a <Link type="KeyEvent" /> struct. The returned <Link type="EventResult" />
indicates whether to accept or reject the event. Rejected events are forwarded to the parent element.

### focus-changed-event(FocusReason)
Invoked when the focus on the `FocusScope` has changed. The argument is a a <Link type="FocusReason" /> enum containing the reason for focus change.

### focus-gained(FocusReason)
Invoked when the `FocusScope` gains focus. The argument is a a <Link type="FocusReason" /> enum containing the reason for focus gain.

### focus-lost(FocusReason)
Invoked when the `FocusScope` loses focus. The argument is a a <Link type="FocusReason" /> enum containing the reason for focus loss.

## `KeyBinding`

Place `KeyBinding` elements inside a `FocusScope` to declare keyboard shortcuts.
KeyBindings use **logical keys**, based on the character a key produces, not physical key positions.

See <Link type="KeyBindingOverview" label="Key Bindings"/> for details.

### Properties of `KeyBinding`

#### keys

<SlintProperty propName="keys" typeName="keys">
The <Link type="keys" label="keys" /> to match against incoming key events.
</SlintProperty>

#### enabled
<SlintProperty propName="enabled" typeName="bool" defaultValue="true">
Whether this KeyBinding is currently enabled. Disabled KeyBinding elements don't consume key events and never invoke their `activated()` callback.
</SlintProperty>

### Callbacks of `KeyBinding`

#### activated()

Invoked when the parent `FocusScope` receives a key event that matches the `keys` of this `KeyBinding`.
