• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Cursor Control
2
3Cursor control attributes control how the cursor is displayed when the mouse pointer is placed over an element.
4
5>  **NOTE**
6>
7>  This feature is supported since API Version 11. Updates will be marked with a superscript to indicate their earliest API version.
8
9
10## cursorControl
11
12### setCursor
13
14setCursor(value: PointerStyle): void
15
16**Atomic service API**: This API can be used in atomic services since API version 12.
17
18Sets the cursor style. This API is a global API.
19
20**Parameters**
21
22| Name| Type| Mandatory| Description|
23| ----- | ------ | ---- | ---- |
24| value | [PointerStyle](../../apis-input-kit/js-apis-pointer.md#pointerstyle) | All consistent  | Cursor style.|
25
26
27### restoreDefault
28
29restoreDefault(): void
30
31**Atomic service API**: This API can be used in atomic services since API version 12.
32
33Restores the cursor to its default style. This API is a global API.
34
35
36## Example
37
38This example demonstrates how to change the mouse cursor style using **setCursor**.
39
40> **NOTE**
41>
42> To avoid confusion with **cursorControl** instances, it is recommended that you obtain a **UIContext** instance using the [getUIContext](../js-apis-arkui-UIContext.md#uicontext) API, and then obtain the **cursorControl** instance bound to the context through the [getCursorController](../js-apis-arkui-UIContext.md#getcursorcontroller12) API.
43
44```ts
45// xxx.ets
46import { pointer } from '@kit.InputKit';
47
48@Entry
49@Component
50struct CursorControlExample {
51  @State text: string = ''
52  controller: TextInputController = new TextInputController()
53
54  build() {
55    Column() {
56      Row().height(200).width(200).backgroundColor(Color.Green).position({x: 150 ,y:70})
57        .onHover((flag) => {
58          if (flag) {
59            // You are advised to use this.getUIContext().getCursorController().setCursor().
60            cursorControl.setCursor(pointer.PointerStyle.EAST)
61          } else {
62            // You are advised to use this.getUIContext().getCursorController().restoreDefault().
63            cursorControl.restoreDefault()
64          }
65        })
66      Row().height(200).width(200).backgroundColor(Color.Blue).position({x: 220 ,y:120})
67        .onHover((flag) => {
68          if (flag) {
69            // You are advised to use this.getUIContext().getCursorController().setCursor().
70            cursorControl.setCursor(pointer.PointerStyle.WEST)
71          } else {
72            // You are advised to use this.getUIContext().getCursorController().restoreDefault().
73            cursorControl.restoreDefault()
74          }
75        })
76    }.width('100%')
77  }
78}
79```
80Diagram:
81
82When the mouse pointer is placed over the blue area, the west arrow cursor is displayed.
83
84![cursor_blue](figures/cursor_blue.jpg)
85
86When the mouse pointer is placed over the green area, the east arrow cursor is displayed.
87
88![cursor_green](figures/cursor_green.jpg)
89