• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Crown Event (Recommended for Circular Screens)
2
3The crown event, supported since API version 18, is triggered by the rotation of the watch crown and reports changes in the rotation angle based on the hardware sampling frequency.
4
5The distribution of crown events depends on the application focus. Only the component that currently has focus can receive the event. Therefore, the component that receives the event must manage its focus status. You can customize focus events. Some built-in components already support interaction with the watch crown. For example, rotating the crown scrolls the scrollbar. In addition, applications can be notified of crown events through a specific API. Currently, the following components support crown events by default: [Slider](../reference/apis-arkui/arkui-ts/ts-basic-components-slider.md), [DatePicker](../reference/apis-arkui/arkui-ts/ts-basic-components-datepicker.md), [TextPicker](../reference/apis-arkui/arkui-ts/ts-basic-components-textpicker.md), [TimePicker](../reference/apis-arkui/arkui-ts/ts-basic-components-timepicker.md), [Scroll](../reference/apis-arkui/arkui-ts/ts-container-scroll.md), [List](../reference/apis-arkui/arkui-ts/ts-container-list.md), [Grid](../reference/apis-arkui/arkui-ts/ts-container-grid.md), [WaterFlow](../reference/apis-arkui/arkui-ts/ts-container-waterflow.md), [ArcList](../reference/apis-arkui/arkui-ts/ts-container-arclist.md), [Refresh](../reference/apis-arkui/arkui-ts/ts-container-refresh.md), and [Swiper](../reference/apis-arkui/arkui-ts/ts-container-swiper.md).
6
7>  **NOTE**
8>
9>  - Only circular screens support crown events.
10
11When a crown event occurs, the **onDigitalCrown** callback is invoked.
12
13```ts
14onDigitalCrown(event: (event?: CrownEvent) => void)
15```
16
17The **event** parameter provides the following information: timestamp, rotation angular velocity, rotation angle, and [crown action](../reference/apis-arkui/arkui-ts/ts-appendix-enums.md#crownaction18).
18
19To enable a component to obtain information such as the rotation angle, use the **onDigitalCrown** API for receiving the crown event. The following example uses the **Text** component to illustrate how to develop a crown event and the precautions to take during development.
20
211. Ensure the component focus.
22
23    Use APIs such as [focusable](../reference/apis-arkui/arkui-ts/ts-universal-attributes-focus.md#focusable), [defaultFocus](../reference/apis-arkui/arkui-ts/ts-universal-attributes-focus.md#defaultfocus9), and [focusOnTouch](../reference/apis-arkui/arkui-ts/ts-universal-attributes-focus.md#focusontouch9) to ensure that the target component can receive focus. For details about focus control, see [Focus Control](../reference/apis-arkui/arkui-ts/ts-universal-attributes-focus.md).
24
25    ```ts
26    Text(this.message)
27      .fontSize(20)
28      .fontColor(Color.White)
29      .backgroundColor("#262626")
30      .textAlign(TextAlign.Center)
31      .focusable(true)
32      .focusOnTouch(true)
33      .defaultFocus(true)
34    ```
352. Register the crown event callback.
36
37    To receive a crown event, you need to register a crown event callback. When a crown event is triggered, the callback function is executed.
38
39    ```ts
40    .onDigitalCrown((event: CrownEvent) => {})
41    ```
423. Understand event fields.
43
44    The crown event provides the timestamp, rotation angular velocity, rotation angle, and crown action. To prevent the event from bubbling up, use [stopPropagation](../reference/apis-arkui/arkui-ts/ts-universal-events-crown.md#crownevent).
45
46    ```ts
47    event.stopPropagation();
48    this.message = "CrownEvent\n\n" + JSON.stringify(event);
49    console.debug("action:%d, angularVelocity:%f, degree:%f, timestamp:%f",
50    event.action, event.angularVelocity, event.degree, event.timestamp);
51    ```
52
53**Example**
54
55```ts
56// xxx.ets
57@Entry
58@Component
59struct CityList {
60  @State message: string = "onDigitalCrown";
61
62  build() {
63    Column() {
64      Row(){
65        Stack() {
66          Text(this.message)
67            .fontSize(20)
68            .fontColor(Color.White)
69            .backgroundColor("#262626")
70            .textAlign(TextAlign.Center)
71            .focusable(true)
72            .focusOnTouch(true)
73            .defaultFocus(true)
74            .borderWidth(2)
75            .width(223).height(223)
76            .borderRadius(110)
77            .onDigitalCrown((event: CrownEvent) => {
78              event.stopPropagation();
79              this.message = "CrownEvent\n\n" + JSON.stringify(event);
80              console.debug("action:%d, angularVelocity:%f, degree:%f, timestamp:%f",
81                event.action, event.angularVelocity, event.degree, event.timestamp);
82            })
83        }.width("100%").height("100%")
84      }.width("100%").height("100%")
85    }
86  }
87}
88```
89
90![crown.gif](../reference/apis-arkui/arkui-ts/figures/crown.gif)
91