1# @ohos.multimodalInput.pointer (Mouse Pointer) 2 3The **pointer** module provides APIs related to pointer attribute management, such as querying and setting pointer attributes. 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.error(`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.error(`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| Type | Description | 72| ------------------- | ------------------- | 73| Promise<void> | Promise that returns no value.| 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.error(`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.error(`Set pointer visible failed, error: ${JSON.stringify(error, [`code`, `message`])}`); 126} 127``` 128 129## pointer.isPointerVisible 130 131isPointerVisible(callback: AsyncCallback<boolean>): void 132 133Obtains 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 visible, 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.error(`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.error(`Get pointer visible failed, error: ${JSON.stringify(error, [`code`, `message`])}`); 164} 165``` 166 167## pointer.isPointerVisible 168 169isPointerVisible(): Promise<boolean> 170 171Obtains 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| Type | Description | 178| ---------------------- | ------------------- | 179| Promise<boolean> | Promise used to return the visible status of the mouse pointer. The value **true** indicates that the mouse pointer is visible, and the value **false** indicates the opposite.| 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.error(`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| Type | 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.error(`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. The value is an integer greater than or equal to **-1**. The value **-1** indicates the global window. | 231| callback | AsyncCallback<[PointerStyle](#pointerstyle)> | Yes | Callback used to return the mouse pointer style.| 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 247window.getLastWindow(this.getUIContext().getHostContext(), (error: BusinessError, win: window.Window) => { 248 if (error.code) { 249 console.error('Failed to obtain the top window. Cause: ' + JSON.stringify(error)); 250 return; 251 } 252 let windowId = win.getWindowProperties().id; 253 if (windowId < 0) { 254 console.log(`Invalid windowId`); 255 return; 256 } 257 try { 258 pointer.getPointerStyle(windowId, (error: Error, style: pointer.PointerStyle) => { 259 console.log(`Get pointer style success, style: ${JSON.stringify(style)}`); 260 }); 261 } catch (error) { 262 console.error(`Get pointer style failed, error: ${JSON.stringify(error, [`code`, `message`])}`); 263 } 264}); 265``` 266 267## pointer.getPointerStyle 268 269getPointerStyle(windowId: number): Promise<PointerStyle> 270 271Obtains the mouse pointer style. This API uses a promise to return the result. 272 273**System capability**: SystemCapability.MultimodalInput.Input.Pointer 274 275**Parameters** 276 277| Name | Type | Mandatory| Description | 278| -------- | ------ | ---- | -------- | 279| windowId | number | Yes | Window ID.| 280 281**Return value** 282 283| Type | Description | 284| ---------------------------------------- | ------------------- | 285| Promise<[PointerStyle](#pointerstyle)> | Promise used to return the mouse pointer style.| 286 287**Error codes** 288 289For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 290 291| ID | Error Message | 292| ---- | --------------------- | 293| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed. | 294 295**Example** 296 297```js 298import { BusinessError } from '@kit.BasicServicesKit'; 299import { window } from '@kit.ArkUI'; 300 301window.getLastWindow(this.getUIContext().getHostContext(), (error: BusinessError, win: window.Window) => { 302 if (error.code) { 303 console.error('Failed to obtain the top window. Cause: ' + JSON.stringify(error)); 304 return; 305 } 306 let windowId = win.getWindowProperties().id; 307 if (windowId < 0) { 308 console.log(`Invalid windowId`); 309 return; 310 } 311 try { 312 pointer.getPointerStyle(windowId).then((style: pointer.PointerStyle) => { 313 console.log(`Get pointer style success, style: ${JSON.stringify(style)}`); 314 }); 315 } catch (error) { 316 console.error(`Get pointer style failed, error: ${JSON.stringify(error, [`code`, `message`])}`); 317 } 318}); 319``` 320 321## pointer.getPointerStyleSync<sup>10+</sup> 322 323getPointerStyleSync(windowId: number): PointerStyle 324 325Obtains the mouse pointer style, such as the east arrow, west arrow, south arrow, and north arrow. This API returns the result synchronously. 326 327**System capability**: SystemCapability.MultimodalInput.Input.Pointer 328 329**Parameters** 330 331| Name | Type | Mandatory| Description | 332| -------- | ------ | ---- | -------- | 333| windowId | number | Yes | Window ID.<br>The default value is **-1**, indicating the global mouse pointer style.| 334 335**Return value** 336 337| Type | Description | 338| ---------------------------------------- | ------------------- | 339| [PointerStyle](#pointerstyle) | Mouse pointer style.| 340 341**Error codes** 342 343For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 344 345| ID | Error Message | 346| ---- | --------------------- | 347| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed. | 348 349**Example** 350 351```js 352import { pointer } from '@kit.InputKit'; 353 354let windowId = -1; 355try { 356 let style: pointer.PointerStyle = pointer.getPointerStyleSync(windowId); 357 console.log(`Get pointer style success, style: ${JSON.stringify(style)}`); 358} catch (error) { 359 console.error(`Get pointer style failed, error: ${JSON.stringify(error, [`code`, `message`])}`); 360} 361``` 362 363## pointer.setPointerStyle 364 365setPointerStyle(windowId: number, pointerStyle: PointerStyle, callback: AsyncCallback<void>): void 366 367Sets the mouse pointer style. This API uses an asynchronous callback to return the result. 368 369**System capability**: SystemCapability.MultimodalInput.Input.Pointer 370 371**Parameters** 372 373| Name | Type | Mandatory | Description | 374| ------------ | ------------------------------ | ---- | ----------------------------------- | 375| windowId | number | Yes | Window ID. | 376| pointerStyle | [PointerStyle](#pointerstyle) | Yes | Pointer style. | 377| callback | AsyncCallback<void> | Yes | Callback used to return the result.| 378 379**Error codes** 380 381For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 382 383| ID | Error Message | 384| ---- | --------------------- | 385| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed. | 386 387**Example** 388 389```js 390import { BusinessError } from '@kit.BasicServicesKit'; 391import { window } from '@kit.ArkUI'; 392 393window.getLastWindow(this.getUIContext().getHostContext(), (error: BusinessError, win: window.Window) => { 394 if (error.code) { 395 console.error('Failed to obtain the top window. Cause: ' + JSON.stringify(error)); 396 return; 397 } 398 let windowId = win.getWindowProperties().id; 399 if (windowId < 0) { 400 console.log(`Invalid windowId`); 401 return; 402 } 403 try { 404 pointer.setPointerStyle(windowId, pointer.PointerStyle.CROSS, error => { 405 console.log(`Set pointer style success`); 406 }); 407 } catch (error) { 408 console.error(`Set pointer style failed, error: ${JSON.stringify(error, [`code`, `message`])}`); 409 } 410}); 411``` 412## pointer.setPointerStyle 413 414setPointerStyle(windowId: number, pointerStyle: PointerStyle): Promise<void> 415 416Sets the mouse pointer style. This API uses a promise to return the result. 417 418**System capability**: SystemCapability.MultimodalInput.Input.Pointer 419 420**Parameters** 421 422| Name | Type | Mandatory | Description | 423| ------------------- | ------------------------------ | ---- | ---------------- | 424| windowId | number | Yes | Window ID. | 425| pointerStyle | [PointerStyle](#pointerstyle) | Yes | Pointer style. | 426 427**Return value** 428 429| Type | Description | 430| ------------------- | ------------------- | 431| Promise<void> | Promise that returns no value.| 432 433**Error codes** 434 435For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 436 437| ID | Error Message | 438| ---- | --------------------- | 439| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed. | 440 441**Example** 442 443```js 444import { BusinessError } from '@kit.BasicServicesKit'; 445import { window } from '@kit.ArkUI'; 446 447window.getLastWindow(this.getUIContext().getHostContext(), (error: BusinessError, win: window.Window) => { 448 if (error.code) { 449 console.error('Failed to obtain the top window. Cause: ' + JSON.stringify(error)); 450 return; 451 } 452 let windowId = win.getWindowProperties().id; 453 if (windowId < 0) { 454 console.log(`Invalid windowId`); 455 return; 456 } 457 try { 458 pointer.setPointerStyle(windowId, pointer.PointerStyle.CROSS).then(() => { 459 console.log(`Set pointer style success`); 460 }); 461 } catch (error) { 462 console.error(`Set pointer style failed, error: ${JSON.stringify(error, [`code`, `message`])}`); 463 } 464}); 465``` 466 467## pointer.setPointerStyleSync<sup>10+</sup> 468 469setPointerStyleSync(windowId: number, pointerStyle: PointerStyle): void 470 471Sets the mouse pointer style. This API returns the result synchronously. 472 473**System capability**: SystemCapability.MultimodalInput.Input.Pointer 474 475**Parameters** 476 477| Name | Type | Mandatory | Description | 478| ------------------- | ------------------------------ | ---- | ---------------- | 479| windowId | number | Yes | Window ID. | 480| pointerStyle | [PointerStyle](#pointerstyle) | Yes | Pointer style. | 481 482**Error codes** 483 484For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 485 486| ID | Error Message | 487| ---- | --------------------- | 488| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed. | 489 490**Example** 491```js 492import { BusinessError } from '@kit.BasicServicesKit'; 493import { window } from '@kit.ArkUI'; 494 495window.getLastWindow(this.getUIContext().getHostContext(), (error: BusinessError, win: window.Window) => { 496 if (error.code) { 497 console.error('Failed to obtain the top window. Cause: ' + JSON.stringify(error)); 498 return; 499 } 500 let windowId = win.getWindowProperties().id; 501 if (windowId < 0) { 502 console.log(`Invalid windowId`); 503 return; 504 } 505 try { 506 pointer.setPointerStyleSync(windowId, pointer.PointerStyle.CROSS); 507 console.log(`Set pointer style success`); 508 } catch (error) { 509 console.error(`getPointerSize failed, error: ${JSON.stringify(error, [`code`, `message`])}`); 510 } 511}); 512``` 513 514## PrimaryButton<sup>10+</sup> 515 516Type of the primary mouse button. 517 518**System capability**: SystemCapability.MultimodalInput.Input.Pointer 519 520| Name | Value | Description | 521| -------------------------------- | ---- | ------ | 522| LEFT | 0 | Left button. | 523| RIGHT | 1 | Right button. | 524 525## RightClickType<sup>10+</sup> 526 527Enumerates shortcut menu triggering modes. 528 529**System capability**: SystemCapability.MultimodalInput.Input.Pointer 530 531| Name | Value | Description | 532| -------------------------------- | ---- | ------ | 533| TOUCHPAD_RIGHT_BUTTON | 1 |Tapping the right-button area of the touchpad.| 534| TOUCHPAD_LEFT_BUTTON | 2 |Tapping the left-button area of the touchpad.| 535| TOUCHPAD_TWO_FINGER_TAP | 3 |Tapping or pressing the touchpad with two fingers.| 536| TOUCHPAD_TWO_FINGER_TAP_OR_RIGHT_BUTTON<sup>20+</sup> | 4 |Tapping or pressing the touchpad with two fingers, or tapping the right-button area of the touchpad.| 537| TOUCHPAD_TWO_FINGER_TAP_OR_LEFT_BUTTON<sup>20+</sup> | 5 |Tapping or pressing the touchpad with two fingers, or tapping the left-button area of the touchpad.| 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 the custom cursor style. 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| Type | 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'; 630 631// app_icon is an example resource. Configure the resource file based on the actual requirements. 632this.getUIContext()?.getHostContext()?.resourceManager.getMediaContent($r("app.media.app_icon")).then((svgFileData) => { 633 const svgBuffer: ArrayBuffer = svgFileData.buffer.slice(0); 634 let svgImagesource: image.ImageSource = image.createImageSource(svgBuffer); 635 let svgDecodingOptions: image.DecodingOptions = {desiredSize: { width: 50, height:50 }}; 636 svgImagesource.createPixelMap(svgDecodingOptions).then((pixelMap) => { 637 window.getLastWindow(this.getUIContext().getHostContext(), (error: BusinessError, win: window.Window) => { 638 let windowId = win.getWindowProperties().id; 639 try { 640 pointer.setCustomCursor(windowId, pixelMap).then(() => { 641 console.log(`setCustomCursor success`); 642 }); 643 } catch (error) { 644 console.error(`setCustomCursor failed, error: ${JSON.stringify(error, [`code`, `message`])}`); 645 } 646 }); 647 }); 648}); 649``` 650## CustomCursor<sup>15+</sup> 651 652Pixel map resource. 653 654**System capability**: SystemCapability.MultimodalInput.Input.Pointer 655| Name | Type | Readable | Writable | Description | 656| -------- | ------- | -------- | -------- | ------- | 657| 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.| 658| 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.| 659| 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.| 660 661## CursorConfig<sup>15+</sup> 662 663Defines the custom cursor configuration. 664 665**System capability**: SystemCapability.MultimodalInput.Input.Pointer 666 667| Name | Type | Readable | Writable | Description | 668| -------- | ------- | -------- | -------- | ------- | 669| 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].| 670 671## pointer.setCustomCursor<sup>15+</sup> 672 673setCustomCursor(windowId: number, cursor: CustomCursor, config: CursorConfig): Promise<void> 674 675Sets the custom cursor style. This API uses a promise to return the result. 676The 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. 677 678**System capability**: SystemCapability.MultimodalInput.Input.Pointer 679 680**Parameters** 681 682| Name | Type | Mandatory | Description | 683| -------- | -------- | -------- | -------- | 684| windowId | number | Yes | Window ID. | 685| cursor | [CustomCursor](js-apis-pointer.md#customcursor15) | Yes | Pixel map resource.| 686| 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].| 687 688**Return value** 689 690| Type | Description | 691| ------------------- | ---------------- | 692| Promise<void> | Promise that returns no value.| 693 694**Error codes** 695 696For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Input Device Error Codes](./errorcode-inputdevice.md). 697 698| ID | Error Message | 699| ---- | --------------------- | 700| 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. | 701| 26500001 | Invalid windowId. | 702 703**Example** 704 705```js 706import { image } from '@kit.ImageKit'; 707import { BusinessError } from '@kit.BasicServicesKit'; 708import { window } from '@kit.ArkUI'; 709 710// app_icon is an example resource. Configure the resource file based on the actual requirements. 711this.getUIContext()?.getHostContext()?.resourceManager.getMediaContent($r("app.media.app_icon")).then((svgFileData) => { 712 const svgBuffer: ArrayBuffer = svgFileData.buffer.slice(0); 713 let svgImagesource: image.ImageSource = image.createImageSource(svgBuffer); 714 let svgDecodingOptions: image.DecodingOptions = {desiredSize: { width: 50, height:50 }}; 715 svgImagesource.createPixelMap(svgDecodingOptions).then((pixelMap) => { 716 window.getLastWindow(this.getUIContext().getHostContext(), (error: BusinessError, win: window.Window) => { 717 let windowId = win.getWindowProperties().id; 718 try { 719 pointer.setCustomCursor(windowId, {pixelMap: pixelMap, focusX: 25, focusY: 25}, {followSystem: false}).then(() => { 720 console.log(`setCustomCursor success`); 721 }); 722 } catch (error) { 723 console.error(`setCustomCursor failed, error: ${JSON.stringify(error, [`code`, `message`])}`); 724 } 725 }); 726 }); 727}); 728``` 729 730## pointer.setCustomCursorSync<sup>11+</sup> 731 732setCustomCursorSync(windowId: number, pixelMap: image.PixelMap, focusX?: number, focusY?: number): void 733 734Sets a custom cursor. This API returns the result synchronously. 735 736**System capability**: SystemCapability.MultimodalInput.Input.Pointer 737 738**Parameters** 739 740| Name | Type | Mandatory | Description | 741| ----- | ------ | ---- | ----------------------------------- | 742| windowId | number | Yes | Window ID. The value must be an integer greater than 0. | 743| pixelMap | [image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7) | Yes | Pixel map resource.| 744| focusX | number | No | Focus x of the custom cursor. The value is greater than or equal to **0**. The default value is **0**.| 745| focusY | number | No | Focus y of the custom cursor. The value is greater than or equal to **0**. The default value is **0**.| 746 747**Error codes** 748 749For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 750 751| ID | Error Message | 752| ---- | --------------------- | 753| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed. | 754 755**Example** 756 757```js 758import { image } from '@kit.ImageKit'; 759import { BusinessError } from '@kit.BasicServicesKit'; 760import { window } from '@kit.ArkUI'; 761 762// app_icon is an example resource. Configure the resource file based on the actual requirements. 763const svgFileData = this.getUIContext()?.getHostContext()?.resourceManager.getMediaContent($r("app.media.app_icon")).then((svgFileData) => { 764 const svgBuffer: ArrayBuffer = svgFileData.buffer.slice(0); 765 let svgImagesource: image.ImageSource = image.createImageSource(svgBuffer); 766 let svgDecodingOptions: image.DecodingOptions = {desiredSize: { width: 50, height:50 }}; 767 svgImagesource.createPixelMap(svgDecodingOptions).then((pixelMap) => { 768 window.getLastWindow(this.getUIContext().getHostContext(), (error: BusinessError, win: window.Window) => { 769 let windowId = win.getWindowProperties().id; 770 try { 771 pointer.setCustomCursorSync(windowId, pixelMap, 25, 25); 772 console.log(`setCustomCursorSync success`); 773 } catch (error) { 774 console.error(`setCustomCursorSync failed, error: ${JSON.stringify(error, [`code`, `message`])}`); 775 } 776 }); 777 }); 778}); 779``` 780
