---
title: "TouchArea"
description: "TouchArea element api."
---
import SlintProperty from '@slint/common-files/src/components/SlintProperty.astro';
import CodeSnippetMD from '@slint/common-files/src/components/CodeSnippetMD.astro';
import EventResult from '/src/content/docs/generated/reference/enums/_EventResult.md';
import PointerEvent from '/src/content/docs/generated/reference/structs/_PointerEvent.md';
import PointerScrollEvent from '/src/content/docs/generated/reference/structs/_PointerScrollEvent.md';
import NotInSC from '@slint/common-files/src/components/NotInSC.astro';
import OnlyInSC from '@slint/common-files/src/components/OnlyInSC.astro';

Use `TouchArea` to control what happens when the region it covers is touched or interacted with
using the mouse. \{#sls.meta.toucharea.purpose}

When not part of a layout, its width or height default to 100% of the parent element. \{#sls.ref.toucharea.size}


<NotInSC>
```slint playground
export component Example inherits Window {
    width: 200px;
    height: 100px;
    area := TouchArea {
        width: parent.width;
        height: parent.height;
        clicked => {
            rect2.background = #ff0;
        }
    }
    Rectangle {
        x:0;
        width: parent.width / 2;
        height: parent.height;
        background: area.pressed ? blue: red;
    }
    rect2 := Rectangle {
        x: parent.width / 2;
        width: parent.width / 2;
        height: parent.height;
    }
}
```
</NotInSC>

## Properties

### enabled
<SlintProperty propName="enabled" typeName="bool" defaultValue="true">
When disabled, the `TouchArea` doesn't recognize any touch or mouse events and they are
passed through to elements underneath.

<CodeSnippetMD imagePath="/src/assets/generated/touch-area-1.png" imageAlt="Basic syntax" imageWidth="200" imageHeight="100" scale="2">
```slint playground
import { Button, CheckBox } from "std-widgets.slint";

export component Example inherits Window {
    width: 200px; height: 100px;

    VerticalLayout {
        Rectangle {
            Button {
                text: "Try to press me";
            }
            TouchArea {
                enabled: event-blocker.checked;
            }
        }
        event-blocker := CheckBox {
            text: "Block Access";
        }
    }
}
```
</CodeSnippetMD>

:::note{Note}
When `enabled` is set to false while the `TouchArea` is pressed, `pointer-event` will be
invoked with `PointerEventKind.Cancel`, and the `pressed` and `has-hover` properties will
be reset to `false`.
:::
</SlintProperty>

### has-hover
<SlintProperty propName="has-hover" typeName="bool" propertyVisibility="out">
Set to true when the mouse is over the `TouchArea` area.
</SlintProperty>

### mouse-cursor
<SlintProperty propName="mouse-cursor" typeName="MouseCursor">
The mouse cursor when the mouse is hovering the `TouchArea`.
</SlintProperty>

### mouse-x
<SlintProperty propName="mouse-x" typeName="length" propertyVisibility="out">
Set by the `TouchArea` to the position of the mouse within it.
</SlintProperty>

### mouse-y
<SlintProperty propName="mouse-y" typeName="length" propertyVisibility="out">
Set by the `TouchArea` to the position of the mouse within it.
</SlintProperty>

### pressed-x
<SlintProperty propName="pressed-x" typeName="length" propertyVisibility="out">
Set by the `TouchArea` to the position of the mouse at the moment it was last pressed.
</SlintProperty>

### pressed-y
<SlintProperty propName="pressed-y" typeName="length" propertyVisibility="out">
Set by the `TouchArea` to the position of the mouse at the moment it was last pressed.
</SlintProperty>

### pressed
<SlintProperty propName="pressed" typeName="bool" propertyVisibility="out">
Set to `true` by the `TouchArea` when the mouse is pressed over it.
</SlintProperty>

## Callbacks

### clicked()
Invoked when clicked: A finger or the left mouse button is pressed, then released on this element. \{#sls.ref.toucharea.clicked}

### double-clicked()
Invoked when double-clicked. The left mouse button is pressed and released twice on this element in a short
period of time, or the same is done with a finger. The `clicked()` callbacks will be triggered before the `double-clicked()` callback is triggered.

### moved()
The mouse or finger has been moved. This will only be called if the mouse is also pressed or the finger continues to touch
the display. See also **pointer-event(PointerEvent)**.

### pointer-event(event: [PointerEvent](/reference/property-types/builtin-structs/#pointerevent))
<PointerEvent />

### scroll-event(event: [PointerScrollEvent](/reference/property-types/builtin-structs/#pointerscrollevent)) -> [EventResult](/reference/property-types/builtin-enums/#eventresult)
Invoked when the mouse wheel was rotated or another scroll gesture was made.
The `PointerScrollEvent` argument contains information about how much to scroll in what direction.
<PointerScrollEvent />
The returned `EventResult`indicates whether to accept or ignore the event. Ignored events are
forwarded to the parent element.
<EventResult />