# Touch Event
A touch event is triggered when a finger is pressed against, swipes on, or is lifted from a component.
> **NOTE**
>
> This event is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version.
## Events
| Name | Bubbling Supported| Description |
| ------------------------------------------------------------ | -------- | ------------------------------------------------------------ |
| onTouch(event: (event: TouchEvent) => void) | Yes | Invoked when a touch event is triggered. For details about **event**, see [TouchEvent](#touchevent).|
## TouchEvent
| Name | Type | Description |
| ------------------- | ---------------------------------------- | ------------ |
| type | [TouchType](ts-appendix-enums.md#touchtype) | Type of the touch event. |
| touches | Array<[TouchObject](#touchobject)> | All finger information. |
| changedTouches | Array<[TouchObject](#touchobject)> | Finger information changed.|
| stopPropagation | () => void | Stops the event from bubbling upwards or downwards.|
| timestamp8+ | number | Timestamp of the event. It is the interval between the time when the event is triggered and the time when the system starts.
For example, if the system starts at 2023/10/12 11:33 and the touch event is triggered at 2023/10/12 11:34, then the returned timestamp value is 60,000,000,000 ns.
Unit: ns|
| target8+ | [EventTarget](ts-universal-events-click.md#eventtarget8) | Display area of the element that triggers the gesture event.|
| source8+ | [SourceType](ts-gesture-settings.md#sourcetype9)| Event input device.|
### getHistoricalPoints10+
getHistoricalPoints(): Array<HistoricalPoint>
Obtains all historical points of the current frame. The touch event frequency of a frame varies by device, and all touch events of the current frame are referred to as its historical points. This API can be called only in [TouchEvent](#touchevent). You can use this API to obtain the historical points of the current frame when [onTouch](#events) is invoked. [onTouch](#events) is invoked only once for a frame. If the value of [TouchEvent](#touchevent) received by the current frame is greater than 1, the last point of the frame is returned through [onTouch](#events). The remaining points are regarded as historical points.
**Return value**
| Type | Description |
| ------ | ----------------------- |
| Array<[HistoricalPoint](#historicalpoint10)>| Array of historical points.|
## TouchObject
| Name | Type | Description |
| ------- | ------------------------------------------- | ------------------------------------- |
| type | [TouchType](ts-appendix-enums.md#touchtype) | Type of the touch event. |
| id | number | Unique identifier of a finger. |
| x | number | X coordinate of the touch point relative to the upper left corner of the component being touched.
Unit: vp|
| y | number | Y coordinate of the touch point relative to the upper left corner of the component being touched.
Unit: vp|
| windowX10+ | number | X coordinate of the touch point relative to the upper left corner of the application window.
Unit: vp |
| windowY10+ | number | Y coordinate of the touch point relative to the upper left corner of the application window.
Unit: vp |
| displayX10+ | number | X coordinate of the touch point relative to the upper left corner of the application screen.
Unit: vp |
| displayY10+ | number | Y coordinate of the touch point relative to the upper left corner of the application screen.
Unit: vp |
| screenX(deprecated) | number | X coordinate of the touch point relative to the upper left corner of the application window.
Unit: vp
This API is deprecated since API version 10. You are advised to use **windowX** instead. |
| screenY(deprecated) | number | Y coordinate of the touch point relative to the upper left corner of the application window.
Unit: vp
This API is deprecated since API version 10. You are advised to use **windowY** instead. |
## HistoricalPoint10+
| Name | Type | Description |
| ----------- | ----------------------------------- | ----------------------------------------------------------------------------- |
| touchObject | [TouchObject](#touchobject) | Basic information of the historical point. |
| size | number | Size of the contact area between the finger and screen for the historical point.
Default value: **0** |
| force | number | Touch force of the historical point.
Default value: **0**
Value range: [0,1]. A larger value indicates a greater touch force.
The support for this API varies by device. Currently, it is only available on tablets.|
| timestamp | number | Timestamp of the historical point. It is the interval between the time when the event is triggered and the time when the system starts.
Unit: ns |
## Example
```ts
// xxx.ets
@Entry
@Component
struct TouchExample {
@State text: string = ''
@State eventType: string = ''
build() {
Column() {
Button('Touch').height(40).width(100)
.onTouch((event?: TouchEvent) => {
if(event){
if (event.type === TouchType.Down) {
this.eventType = 'Down'
}
if (event.type === TouchType.Up) {
this.eventType = 'Up'
}
if (event.type === TouchType.Move) {
this.eventType = 'Move'
}
this.text = 'TouchType:' + this.eventType + '\nDistance between touch point and touch element:\nx: '
+ event.touches[0].x + '\n' + 'y: ' + event.touches[0].y + '\nComponent globalPos:('
+ event.target.area.globalPosition.x + ',' + event.target.area.globalPosition.y + ')\nwidth:'
+ event.target.area.width + '\nheight:' + event.target.area.height
}
})
Button('Touch').height(50).width(200).margin(20)
.onTouch((event?: TouchEvent) => {
if(event){
if (event.type === TouchType.Down) {
this.eventType = 'Down'
}
if (event.type === TouchType.Up) {
this.eventType = 'Up'
}
if (event.type === TouchType.Move) {
this.eventType = 'Move'
}
this.text = 'TouchType:' + this.eventType + '\nDistance between touch point and touch element:\nx: '
+ event.touches[0].x + '\n' + 'y: ' + event.touches[0].y + '\nComponent globalPos:('
+ event.target.area.globalPosition.x + ',' + event.target.area.globalPosition.y + ')\nwidth:'
+ event.target.area.width + '\nheight:' + event.target.area.height
}
})
Text(this.text)
}.width('100%').padding(30)
}
}
```
