1# @ohos.multimodalInput.pointer (Mouse Pointer) 2 3The **pointer** module provides APIs related to pointer attribute management. 4 5> **NOTE** 6> 7> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. 8 9## Modules to Import 10 11```js 12import { pointer } from '@kit.InputKit'; 13``` 14 15## pointer.setPointerVisible 16 17setPointerVisible(visible: boolean, callback: AsyncCallback<void>): void 18 19Sets the visible status of the mouse pointer. This API uses an asynchronous callback to return the result. 20 21**System capability**: SystemCapability.MultimodalInput.Input.Pointer 22 23**Parameters** 24 25| Name | Type | Mandatory | Description | 26| -------- | ------------------------- | ---- | ---------------------------------------- | 27| visible | boolean | Yes | Whether the mouse pointer is visible. The value **true** indicates that the mouse pointer is visible, and the value **false** indicates the opposite.| 28| callback | AsyncCallback<void> | Yes | Callback used to return the result.| 29 30**Error codes** 31 32For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 33 34| ID | Error Message | 35| ---- | --------------------- | 36| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed. | 37| 801 | Capability not supported. | 38 39**Example** 40 41```js 42try { 43 pointer.setPointerVisible(true, (error: Error) => { 44 if (error) { 45 console.log(`Set pointer visible failed, error: ${JSON.stringify(error, [`code`, `message`])}`); 46 return; 47 } 48 console.log(`Set pointer visible success`); 49 }); 50} catch (error) { 51 console.log(`Set pointer visible failed, error: ${JSON.stringify(error, [`code`, `message`])}`); 52} 53``` 54 55## pointer.setPointerVisible 56 57setPointerVisible(visible: boolean): Promise<void> 58 59Sets the visible status of the mouse pointer. This API uses a promise to return the result. 60 61**System capability**: SystemCapability.MultimodalInput.Input.Pointer 62 63**Parameters** 64 65| Name | Type | Mandatory | Description | 66| ------- | ------- | ---- | ---------------------------------------- | 67| visible | boolean | Yes | Whether the mouse pointer is visible. The value **true** indicates that the mouse pointer is visible, and the value **false** indicates the opposite.| 68 69**Return value** 70 71| Name | Description | 72| ------------------- | ------------------- | 73| Promise<void> | Promise used to return the result.| 74 75**Error codes** 76 77For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 78 79| ID | Error Message | 80| ---- | --------------------- | 81| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed. | 82| 801 | Capability not supported. | 83 84**Example** 85 86```js 87try { 88 pointer.setPointerVisible(false).then(() => { 89 console.log(`Set pointer visible success`); 90 }); 91} catch (error) { 92 console.log(`Set pointer visible failed, error: ${JSON.stringify(error, [`code`, `message`])}`); 93} 94``` 95 96## pointer.setPointerVisibleSync<sup>10+</sup> 97 98setPointerVisibleSync(visible: boolean): void 99 100Sets the visible status of the mouse pointer. This API returns the result synchronously. 101 102**System capability**: SystemCapability.MultimodalInput.Input.Pointer 103 104**Parameters** 105 106| Name | Type | Mandatory | Description | 107| ------- | ------- | ---- | ---------------------------------------- | 108| visible | boolean | Yes | Whether the mouse pointer is visible. The value **true** indicates that the mouse pointer is visible, and the value **false** indicates the opposite.| 109 110**Error codes** 111 112For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 113 114| ID | Error Message | 115| ---- | --------------------- | 116| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed. | 117 118**Example** 119 120```js 121try { 122 pointer.setPointerVisibleSync(false); 123 console.log(`Set pointer visible success`); 124} catch (error) { 125 console.log(`Set pointer visible failed, error: ${JSON.stringify(error, [`code`, `message`])}`); 126} 127``` 128 129## pointer.isPointerVisible 130 131isPointerVisible(callback: AsyncCallback<boolean>): void 132 133Checks the visible status of the mouse pointer. This API uses an asynchronous callback to return the result. 134 135**System capability**: SystemCapability.MultimodalInput.Input.Pointer 136 137**Parameters** 138 139| Name | Type | Mandatory | Description | 140| -------- | ---------------------------- | ---- | -------------- | 141| callback | AsyncCallback<boolean> | Yes | Callback used to return the result. The value **true** indicates that the mouse pointer is displayed, and the value **false** indicates the opposite.| 142 143**Error codes** 144 145For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 146 147| ID | Error Message | 148| ---- | --------------------- | 149| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed. | 150 151**Example** 152 153```js 154try { 155 pointer.isPointerVisible((error: Error, visible: boolean) => { 156 if (error) { 157 console.log(`Get pointer visible failed, error: ${JSON.stringify(error, [`code`, `message`])}`); 158 return; 159 } 160 console.log(`Get pointer visible success, visible: ${JSON.stringify(visible)}`); 161 }); 162} catch (error) { 163 console.log(`Get pointer visible failed, error: ${JSON.stringify(error, [`code`, `message`])}`); 164} 165``` 166 167## pointer.isPointerVisible 168 169isPointerVisible(): Promise<boolean> 170 171Checks the visible status of the mouse pointer. This API uses a promise to return the result. 172 173**System capability**: SystemCapability.MultimodalInput.Input.Pointer 174 175**Return value** 176 177| Name | Description | 178| ---------------------- | ------------------- | 179| Promise<boolean> | Promise used to return the result.| 180 181**Example** 182 183```js 184try { 185 pointer.isPointerVisible().then((visible: boolean) => { 186 console.log(`Get pointer visible success, visible: ${JSON.stringify(visible)}`); 187 }); 188} catch (error) { 189 console.log(`Get pointer visible failed, error: ${JSON.stringify(error, [`code`, `message`])}`); 190} 191``` 192 193## pointer.isPointerVisibleSync<sup>10+</sup> 194 195isPointerVisibleSync(): boolean 196 197Obtains the visible status of the mouse pointer. This API returns the result synchronously. 198 199**System capability**: SystemCapability.MultimodalInput.Input.Pointer 200 201**Return value** 202 203| Name | Description | 204| ---------------------- | ------------------- | 205| boolean | Visible status of the mouse pointer. The value **true** indicates that the mouse pointer is visible, and the value **false** indicates the opposite.| 206 207**Example** 208 209```js 210try { 211 let visible: boolean = pointer.isPointerVisibleSync(); 212 console.log(`Get pointer visible success, visible: ${JSON.stringify(visible)}`); 213} catch (error) { 214 console.log(`Get pointer visible failed, error: ${JSON.stringify(error, [`code`, `message`])}`); 215} 216``` 217 218## pointer.getPointerStyle 219 220getPointerStyle(windowId: number, callback: AsyncCallback<PointerStyle>): void 221 222Obtains the mouse pointer style. This API uses an asynchronous callback to return the result. 223 224**System capability**: SystemCapability.MultimodalInput.Input.Pointer 225 226**Parameters** 227 228| Name | Type | Mandatory | Description | 229| -------- | ---------------------------------------- | ---- | -------------- | 230| windowId | number | Yes | Window ID. | 231| callback | AsyncCallback<[PointerStyle](#pointerstyle)> | Yes | Callback used to return the result.| 232 233**Error codes** 234 235For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 236 237| ID | Error Message | 238| ---- | --------------------- | 239| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed. | 240 241**Example** 242 243```js 244import { BusinessError } from '@kit.BasicServicesKit'; 245import { window } from '@kit.ArkUI'; 246 247let context = getContext(this); 248window.getLastWindow(context, (error: BusinessError, win: window.Window) => { 249 if (error.code) { 250 console.error('Failed to obtain the top window. Cause: ' + JSON.stringify(error)); 251 return; 252 } 253 let windowId = win.getWindowProperties().id; 254 if (windowId < 0) { 255 console.log(`Invalid windowId`); 256 return; 257 } 258 try { 259 pointer.getPointerStyle(windowId, (error: Error, style: pointer.PointerStyle) => { 260 console.log(`Get pointer style success, style: ${JSON.stringify(style)}`); 261 }); 262 } catch (error) { 263 console.log(`Get pointer style failed, error: ${JSON.stringify(error, [`code`, `message`])}`); 264 } 265}); 266``` 267 268## pointer.getPointerStyle 269 270getPointerStyle(windowId: number): Promise<PointerStyle> 271 272Obtains the mouse pointer style. This API uses a promise to return the result. 273 274**System capability**: SystemCapability.MultimodalInput.Input.Pointer 275 276**Parameters** 277 278| Name | Type | Mandatory| Description | 279| -------- | ------ | ---- | -------- | 280| windowId | number | Yes | Window ID.| 281 282**Return value** 283 284| Name | Description | 285| ---------------------------------------- | ------------------- | 286| Promise<[PointerStyle](#pointerstyle)> | Promise used to return the result.| 287 288**Error codes** 289 290For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 291 292| ID | Error Message | 293| ---- | --------------------- | 294| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed. | 295 296**Example** 297 298```js 299import { BusinessError } from '@kit.BasicServicesKit'; 300import { window } from '@kit.ArkUI'; 301 302let context = getContext(this); 303window.getLastWindow(context, (error: BusinessError, win: window.Window) => { 304 if (error.code) { 305 console.error('Failed to obtain the top window. Cause: ' + JSON.stringify(error)); 306 return; 307 } 308 let windowId = win.getWindowProperties().id; 309 if (windowId < 0) { 310 console.log(`Invalid windowId`); 311 return; 312 } 313 try { 314 pointer.getPointerStyle(windowId).then((style: pointer.PointerStyle) => { 315 console.log(`Get pointer style success, style: ${JSON.stringify(style)}`); 316 }); 317 } catch (error) { 318 console.log(`Get pointer style failed, error: ${JSON.stringify(error, [`code`, `message`])}`); 319 } 320}); 321``` 322 323## pointer.getPointerStyleSync<sup>10+</sup> 324 325getPointerStyleSync(windowId: number): PointerStyle 326 327Obtains the mouse pointer style. This API returns the result synchronously. 328 329**System capability**: SystemCapability.MultimodalInput.Input.Pointer 330 331**Parameters** 332 333| Name | Type | Mandatory| Description | 334| -------- | ------ | ---- | -------- | 335| windowId | number | Yes | Window ID.<br>The default value is **-1**, indicating the global mouse pointer style.| 336 337**Return value** 338 339| Name | Description | 340| ---------------------------------------- | ------------------- | 341| [PointerStyle](#pointerstyle) | Mouse pointer style.| 342 343**Error codes** 344 345For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 346 347| ID | Error Message | 348| ---- | --------------------- | 349| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed. | 350 351**Example** 352 353```js 354import { pointer } from '@kit.InputKit'; 355 356let windowId = -1; 357try { 358 let style: pointer.PointerStyle = pointer.getPointerStyleSync(windowId); 359 console.log(`Get pointer style success, style: ${JSON.stringify(style)}`); 360} catch (error) { 361 console.log(`Get pointer style failed, error: ${JSON.stringify(error, [`code`, `message`])}`); 362} 363``` 364 365## pointer.setPointerStyle 366 367setPointerStyle(windowId: number, pointerStyle: PointerStyle, callback: AsyncCallback<void>): void 368 369Sets the mouse pointer style. This API uses an asynchronous callback to return the result. 370 371**System capability**: SystemCapability.MultimodalInput.Input.Pointer 372 373**Parameters** 374 375| Name | Type | Mandatory | Description | 376| ------------ | ------------------------------ | ---- | ----------------------------------- | 377| windowId | number | Yes | Window ID. | 378| pointerStyle | [PointerStyle](#pointerstyle) | Yes | Pointer style. | 379| callback | AsyncCallback<void> | Yes | Callback used to return the result.| 380 381**Error codes** 382 383For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 384 385| ID | Error Message | 386| ---- | --------------------- | 387| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed. | 388 389**Example** 390 391```js 392import { BusinessError } from '@kit.BasicServicesKit'; 393import { window } from '@kit.ArkUI'; 394 395window.getLastWindow(getContext(), (error: BusinessError, win: window.Window) => { 396 if (error.code) { 397 console.error('Failed to obtain the top window. Cause: ' + JSON.stringify(error)); 398 return; 399 } 400 let windowId = win.getWindowProperties().id; 401 if (windowId < 0) { 402 console.log(`Invalid windowId`); 403 return; 404 } 405 try { 406 pointer.setPointerStyle(windowId, pointer.PointerStyle.CROSS, error => { 407 console.log(`Set pointer style success`); 408 }); 409 } catch (error) { 410 console.log(`Set pointer style failed, error: ${JSON.stringify(error, [`code`, `message`])}`); 411 } 412}); 413``` 414## pointer.setPointerStyle 415 416setPointerStyle(windowId: number, pointerStyle: PointerStyle): Promise<void> 417 418Sets the mouse pointer style. This API uses a promise to return the result. 419 420**System capability**: SystemCapability.MultimodalInput.Input.Pointer 421 422**Parameters** 423 424| Name | Type | Mandatory | Description | 425| ------------------- | ------------------------------ | ---- | ---------------- | 426| windowId | number | Yes | Window ID. | 427| pointerStyle | [PointerStyle](#pointerstyle) | Yes | Pointer style. | 428 429**Return value** 430 431| Name | Description | 432| ------------------- | ------------------- | 433| Promise<void> | Promise used to return the result.| 434 435**Error codes** 436 437For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 438 439| ID | Error Message | 440| ---- | --------------------- | 441| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed. | 442 443**Example** 444 445```js 446import { BusinessError } from '@kit.BasicServicesKit'; 447import { window } from '@kit.ArkUI'; 448 449window.getLastWindow(getContext(), (error: BusinessError, win: window.Window) => { 450 if (error.code) { 451 console.error('Failed to obtain the top window. Cause: ' + JSON.stringify(error)); 452 return; 453 } 454 let windowId = win.getWindowProperties().id; 455 if (windowId < 0) { 456 console.log(`Invalid windowId`); 457 return; 458 } 459 try { 460 pointer.setPointerStyle(windowId, pointer.PointerStyle.CROSS).then(() => { 461 console.log(`Set pointer style success`); 462 }); 463 } catch (error) { 464 console.log(`Set pointer style failed, error: ${JSON.stringify(error, [`code`, `message`])}`); 465 } 466}); 467``` 468 469## pointer.setPointerStyleSync<sup>10+</sup> 470 471setPointerStyleSync(windowId: number, pointerStyle: PointerStyle): void 472 473Sets the mouse pointer style. This API returns the result synchronously. 474 475**System capability**: SystemCapability.MultimodalInput.Input.Pointer 476 477**Parameters** 478 479| Name | Type | Mandatory | Description | 480| ------------------- | ------------------------------ | ---- | ---------------- | 481| windowId | number | Yes | Window ID. | 482| pointerStyle | [PointerStyle](#pointerstyle) | Yes | Pointer style. | 483 484**Error codes** 485 486For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 487 488| ID | Error Message | 489| ---- | --------------------- | 490| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed. | 491 492**Example** 493```js 494import { BusinessError } from '@kit.BasicServicesKit'; 495import { window } from '@kit.ArkUI'; 496 497window.getLastWindow(getContext(), (error: BusinessError, win: window.Window) => { 498 if (error.code) { 499 console.error('Failed to obtain the top window. Cause: ' + JSON.stringify(error)); 500 return; 501 } 502 let windowId = win.getWindowProperties().id; 503 if (windowId < 0) { 504 console.log(`Invalid windowId`); 505 return; 506 } 507 try { 508 pointer.setPointerStyleSync(windowId, pointer.PointerStyle.CROSS); 509 console.log(`Set pointer style success`); 510 } catch (error) { 511 console.log(`getPointerSize failed, error: ${JSON.stringify(error, [`code`, `message`])}`); 512 } 513}); 514``` 515 516## PrimaryButton<sup>10+</sup> 517 518Type of the primary mouse button. 519 520**System capability**: SystemCapability.MultimodalInput.Input.Pointer 521 522| Name | Value | Description | 523| -------------------------------- | ---- | ------ | 524| LEFT | 0 | Left mouse button. | 525| RIGHT | 1 | Right mouse button. | 526 527## RightClickType<sup>10+</sup> 528 529Enumerates shortcut menu triggering modes. 530 531**System capability**: SystemCapability.MultimodalInput.Input.Pointer 532 533| Name | Value | Description | 534| -------------------------------- | ---- | ------ | 535| TOUCHPAD_RIGHT_BUTTON | 1 |Tapping the right-button area of the touchpad.| 536| TOUCHPAD_LEFT_BUTTON | 2 |Tapping the left-button area of the touchpad.| 537| TOUCHPAD_TWO_FINGER_TAP | 3 |Tapping or pressing the touchpad with two fingers.| 538 539## PointerStyle 540 541Enumerates mouse pointer styles. 542 543**System capability**: SystemCapability.MultimodalInput.Input.Pointer 544 545| Name | Value | Description |Legend| 546| -------------------------------- | ---- | ------ |------ | 547| DEFAULT | 0 | Default || 548| EAST | 1 | East arrow || 549| WEST | 2 | West arrow || 550| SOUTH | 3 | South arrow || 551| NORTH | 4 | North arrow || 552| WEST_EAST | 5 | West-east arrow || 553| NORTH_SOUTH | 6 | North-south arrow || 554| NORTH_EAST | 7 | North-east arrow || 555| NORTH_WEST | 8 | North-west arrow || 556| SOUTH_EAST | 9 | South-east arrow || 557| SOUTH_WEST | 10 | South-west arrow || 558| NORTH_EAST_SOUTH_WEST | 11 | North-east and south-west adjustment|| 559| NORTH_WEST_SOUTH_EAST | 12 | North-west and south-east adjustment|| 560| CROSS | 13 | Cross (accurate selection) || 561| CURSOR_COPY | 14 | Copy || 562| CURSOR_FORBID | 15 | Forbid || 563| COLOR_SUCKER | 16 | Sucker || 564| HAND_GRABBING | 17 | Grabbing hand || 565| HAND_OPEN | 18 | Opening hand || 566| HAND_POINTING | 19 | Hand-shaped pointer || 567| HELP | 20 | Help || 568| MOVE | 21 | Move || 569| RESIZE_LEFT_RIGHT | 22 | Left and right resizing|| 570| RESIZE_UP_DOWN | 23 | Up and down resizing|| 571| SCREENSHOT_CHOOSE | 24 | Screenshot crosshair|| 572| SCREENSHOT_CURSOR | 25 | Screenshot || 573| TEXT_CURSOR | 26 | Text selection || 574| ZOOM_IN | 27 | Zoom in || 575| ZOOM_OUT | 28 | Zoom out || 576| MIDDLE_BTN_EAST | 29 | Scrolling east || 577| MIDDLE_BTN_WEST | 30 | Scrolling west || 578| MIDDLE_BTN_SOUTH | 31 | Scrolling south |  | 579| MIDDLE_BTN_NORTH | 32 | Scrolling north || 580| MIDDLE_BTN_NORTH_SOUTH | 33 | Scrolling north-south || 581| MIDDLE_BTN_NORTH_EAST | 34 | Scrolling north-east || 582| MIDDLE_BTN_NORTH_WEST | 35 | Scrolling north-west || 583| MIDDLE_BTN_SOUTH_EAST | 36 | Scrolling south-east || 584| MIDDLE_BTN_SOUTH_WEST | 37 | Scrolling south-west || 585| MIDDLE_BTN_NORTH_SOUTH_WEST_EAST | 38 | Moving as a cone in four directions|| 586| HORIZONTAL_TEXT_CURSOR<sup>10+</sup> | 39 | Horizontal text selection|| 587| CURSOR_CROSS<sup>10+</sup> | 40 | Cross|| 588| CURSOR_CIRCLE<sup>10+</sup> | 41 | Circle|| 589| LOADING<sup>10+</sup> | 42 | Animation loading|<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 590| RUNNING<sup>10+</sup> | 43 | Animation running in the background|<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 591| MIDDLE_BTN_EAST_WEST<sup>18+</sup> | 44 | Scrolling east-west|| 592 593## pointer.setCustomCursor<sup>11+</sup> 594 595setCustomCursor(windowId: number, pixelMap: image.PixelMap, focusX?: number, focusY?: number): Promise<void> 596 597Sets a custom cursor. This API uses a promise to return the result. 598 599**System capability**: SystemCapability.MultimodalInput.Input.Pointer 600 601**Parameters** 602 603| Name | Type | Mandatory | Description | 604| ----- | ------ | ---- | ----------------------------------- | 605| windowId | number | Yes | Window ID. | 606| pixelMap | [image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7) | Yes | Pixel map resource.| 607| focusX | number | No | Focus x of the custom cursor. The value is greater than or equal to **0**. The default value is **0**.| 608| focusY | number | No | Focus y of the custom cursor. The value is greater than or equal to **0**. The default value is **0**.| 609 610**Return value** 611 612| Name | Description | 613| ------------------- | ---------------- | 614| Promise<void> | Promise that returns no value.| 615 616**Error codes** 617 618For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 619 620| ID | Error Message | 621| ---- | --------------------- | 622| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed. | 623 624**Example** 625 626```js 627import { image } from '@kit.ImageKit'; 628import { BusinessError } from '@kit.BasicServicesKit'; 629import { window } from '@kit.ArkUI'; 630getContext().resourceManager.getMediaContent($r("app.media.app_icon")).then((svgFileData) => { 631 const svgBuffer: ArrayBuffer = svgFileData.buffer.slice(0); 632 let svgImagesource: image.ImageSource = image.createImageSource(svgBuffer); 633 let svgDecodingOptions: image.DecodingOptions = {desiredSize: { width: 50, height:50 }}; 634 svgImagesource.createPixelMap(svgDecodingOptions).then((pixelMap) => { 635 window.getLastWindow(getContext(), (error: BusinessError, win: window.Window) => { 636 let windowId = win.getWindowProperties().id; 637 try { 638 pointer.setCustomCursor(windowId, pixelMap).then(() => { 639 console.log(`setCustomCursor success`); 640 }); 641 } catch (error) { 642 console.log(`setCustomCursor failed, error: ${JSON.stringify(error, [`code`, `message`])}`); 643 } 644 }); 645 }); 646}); 647``` 648## CustomCursor<sup>15+</sup> 649 650Pixel map resource. 651 652**System capability**: SystemCapability.MultimodalInput.Input.Pointer 653| Name | Type | Readable | Writable | Description | 654| -------- | ------- | -------- | -------- | ------- | 655| pixelMap | [image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7) | No | No | Defines a custom cursor. The minimum size is subject to the minimum limit of the image. The maximum size is 256 x 256 px.| 656| focusX | number | No | Yes | Horizontal coordinate of the cursor focus. The coordinates are restricted by the size of the custom cursor. The minimum value is **0**, and the maximum value is the maximum width of the image. The default value is **0** if the parameter is left empty.| 657| focusY | number | No | Yes | Vertical coordinate of the cursor focus. The coordinates are restricted by the size of the custom cursor. The minimum value is **0**, and the maximum value is the maximum height of the image. The default value is **0** if the parameter is left empty.| 658 659## CursorConfig<sup>15+</sup> 660 661Defines the custom cursor configuration. 662 663**System capability**: SystemCapability.MultimodalInput.Input.Pointer 664 665| Name | Type | Readable | Writable | Description | 666| -------- | ------- | -------- | -------- | ------- | 667| followSystem | boolean | No | No | Whether to adjust the cursor size based on system settings. The value **true** means to adjust the cursor size based on system settings, and the value **false** means to use the custom cursor size. The adjustment range is [size of the cursor image, 256 x 256].| 668 669## pointer.setCustomCursor<sup>15+</sup> 670 671setCustomCursor(windowId: number, cursor: CustomCursor, config: CursorConfig): Promise<void> 672 673Sets the custom cursor style. This API uses a promise to return the result. 674The cursor may be switched back to the system style in the following cases: application window layout change, hot zone switching, page redirection, moving of the cursor out of the window and then back to the window, or moving of the cursor in different areas of the window. In this case, you need to reset the cursor style. 675 676**System capability**: SystemCapability.MultimodalInput.Input.Pointer 677 678**Parameters** 679 680| Name | Type | Mandatory | Description | 681| -------- | -------- | -------- | -------- | 682| windowId | number | Yes | Window ID. | 683| cursor | [CustomCursor](js-apis-pointer.md#customcursor15) | Yes | Pixel map resource.| 684| config | [CursorConfig](js-apis-pointer.md#cursorconfig15) | Yes | Custom cursor configuration, which specifies whether to adjust the cursor size based on system settings. If **followSystem** in **CursorConfig** is set to **true**, the supported adjustment range is [size of the cursor image, 256 x 256].| 685 686**Return value** 687 688| Name | Description | 689| ------------------- | ---------------- | 690| Promise<void> | Promise that returns no value.| 691 692**Error codes** 693 694For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Input Device Error Codes](./errorcode-inputdevice.md). 695 696| ID | Error Message | 697| ---- | --------------------- | 698| 401 | Parameter error. Possible causes: 1. Abnormal windowId parameter passed in. 2. Abnormal pixelMap parameter passed in; 3. Abnormal focusX parameter passed in.4. Abnormal focusY parameter passed in. | 699| 26500001 | Invalid windowId. | 700 701**Example** 702 703```js 704import { image } from '@kit.ImageKit'; 705import { BusinessError } from '@kit.BasicServicesKit'; 706import { window } from '@kit.ArkUI'; 707getContext().resourceManager.getMediaContent($r("app.media.app_icon")).then((svgFileData) => { 708 const svgBuffer: ArrayBuffer = svgFileData.buffer.slice(0); 709 let svgImagesource: image.ImageSource = image.createImageSource(svgBuffer); 710 let svgDecodingOptions: image.DecodingOptions = {desiredSize: { width: 50, height:50 }}; 711 svgImagesource.createPixelMap(svgDecodingOptions).then((pixelMap) => { 712 window.getLastWindow(getContext(), (error: BusinessError, win: window.Window) => { 713 let windowId = win.getWindowProperties().id; 714 try { 715 pointer.setCustomCursor(windowId, {pixelMap: pixelMap, focusX: 25, focusY: 25}, {followSystem: false}).then(() => { 716 console.log(`setCustomCursor success`); 717 }); 718 } catch (error) { 719 console.log(`setCustomCursor failed, error: ${JSON.stringify(error, [`code`, `message`])}`); 720 } 721 }); 722 }); 723}); 724``` 725 726## pointer.setCustomCursorSync<sup>11+</sup> 727 728setCustomCursorSync(windowId: number, pixelMap: image.PixelMap, focusX?: number, focusY?: number): void 729 730Sets a custom cursor. This API returns the result synchronously. 731 732**System capability**: SystemCapability.MultimodalInput.Input.Pointer 733 734**Parameters** 735 736| Name | Type | Mandatory | Description | 737| ----- | ------ | ---- | ----------------------------------- | 738| windowId | number | Yes | Window ID. | 739| pixelMap | [image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7) | Yes | Pixel map resource.| 740| focusX | number | No | Focus x of the custom cursor. The value is greater than or equal to **0**. The default value is **0**.| 741| focusY | number | No | Focus y of the custom cursor. The value is greater than or equal to **0**. The default value is **0**.| 742 743**Error codes** 744 745For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 746 747| ID | Error Message | 748| ---- | --------------------- | 749| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed. | 750 751**Example** 752 753```js 754import { image } from '@kit.ImageKit'; 755import { BusinessError } from '@kit.BasicServicesKit'; 756import { window } from '@kit.ArkUI'; 757const svgFileData = getContext().resourceManager.getMediaContent($r("app.media.app_icon")).then((svgFileData) => { 758 const svgBuffer: ArrayBuffer = svgFileData.buffer.slice(0); 759 let svgImagesource: image.ImageSource = image.createImageSource(svgBuffer); 760 let svgDecodingOptions: image.DecodingOptions = {desiredSize: { width: 50, height:50 }}; 761 svgImagesource.createPixelMap(svgDecodingOptions).then((pixelMap) => { 762 window.getLastWindow(getContext(), (error: BusinessError, win: window.Window) => { 763 let windowId = win.getWindowProperties().id; 764 try { 765 pointer.setCustomCursorSync(windowId, pixelMap, 25, 25); 766 console.log(`setCustomCursorSync success`); 767 } catch (error) { 768 console.log(`setCustomCursorSync failed, error: ${JSON.stringify(error, [`code`, `message`])}`); 769 } 770 }); 771 }); 772}); 773``` 774
